Init for public release

Author: uzyn

.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  push:
+
+jobs:
+  test:
+    strategy:
+      matrix:
+        zig-version: [0.14.0, master]
+
+    name: Ubuntu / Zig ${{ matrix.zig-version }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Zig
+        uses: mlugg/setup-zig@main
+        with:
+          version: ${{ matrix.zig-version }}
+
+      - name: Build library
+        run: zig build
+
+      - name: Run tests
+        run: zig build test --summary all
+
+      - name: Check formatting
+        run: zig fmt --check .

.gitignore

@@ -0,0 +1,4 @@
+.DS_Store
+zig-out/
+.zig-cache/
+/ref-*

README.md

@@ -0,0 +1,195 @@
+# passcay
+
+[![Tests](https://github.com/uzyn/passcay/actions/workflows/test.yml/badge.svg)](https://github.com/uzyn/passcay/actions/workflows/test.yml)
+
+
+**Minimal**, **fast** and **secure** Passkey (WebAuthn) relying party (RP) library for Zig.
+
+## Features
+
+- Passkey WebAuthn registration
+- Passkey WebAuthn authentication/verification (login)
+- Attestation-less passkey usage (privacy-preserving, does not affect security)
+- Cryptographic signature verification. Supports both ES256 & RS256, covering 100% of all Passkey authenticators today.
+- Secure challenge generation
+
+## Dependencies
+
+Compiles and tested on both Zig stable 0.14+ and nightly (0.15+).
+
+Dynamically linked to system's OpenSSL for crypto verification.
+
+Works on Linux and macOS. Not yet on Windows.
+
+### Installation
+
+Add `passcay` to your `build.zig.zon` dependencies:
+
+```zig
+.dependencies = .{
+    .passcay = .{
+        .url = "https://github.com/uzyn/passcay/archive/main.tar.gz",
+        // Optionally pin to a specific commit hash
+    },
+},
+```
+
+And update your `build.zig` to load `passcay`:
+
+```zig
+const passcay = b.dependency("passcay", .{
+    .optimize = optimize,
+    .target = target,
+});
+exe.root_module.addImport("passcay", passcay.module("passcay"));
+```
+
+## Build & Test
+
+```sh
+zig build
+zig build test --summary all
+```
+
+
+## Usage
+
+### Registration
+
+```zig
+const passcay = @import("passcay");
+
+const input = passcay.register.RegVerifyInput{
+     .attestation_object = attestation_object,
+     .client_data_json   = client_data_json,
+};
+
+const expectations = passcay.register.RegVerifyExpectations{
+     .challenge               = challenge,
+     .origin                  = "https://example.com",
+     .rp_id                   = "example.com",
+     .require_user_verification = true,
+};
+
+const reg = try passcay.register.verify(allocator, input, expectations);
+
+// Save reg.credential_id, reg.public_key, and reg.sign_count
+// to database for authentication
+```
+
+Store the following in database for authentication:
+- `reg.credential_id`
+- `reg.public_key`
+- `reg.sign_count` (usually starts at 0)
+
+### Authentication
+
+```zig
+const challenge = try passcay.challenge.generate(allocator);
+// Pass challenge to client-side for authentication
+
+const input = passcay.auth.AuthVerifyInput{
+    .authenticator_data = authenticator_data,
+    .client_data_json = client_data_json,
+    .signature = signature,
+};
+
+const expectations = passcay.auth.AuthVerifyExpectations{
+    .public_key = user_public_key, // Retrieve public_key from database, given credential_id from navigator.credentials.get
+    .challenge = challenge,
+    .origin = "https://example.com",
+    .rp_id = "example.com",
+    .require_user_verification = true,
+    .enable_sign_count_check = true,
+    .known_sign_count = stored_sign_count,
+};
+
+const auth = try passcay.auth.verify(allocator, input, expectations);
+```
+
+Update the stored sign count with `auth.recommended_sign_count`:
+
+### Client-Side (JavaScript)
+
+```javascript
+// Registration
+const regOptions = {
+    challenge: base64UrlDecode(challenge),
+    rp: {
+        name: "Example",
+        id: "example.com", // Must match your domain without protocol/port
+    },
+    user: { name: username },
+    pubKeyCredParams: [
+        { type: "public-key", alg: -7 },   // ES256 (Most widely supported)
+        { type: "public-key", alg: -257 }, // RS256
+    ],
+    authenticatorSelection: {
+        authenticatorAttachment: "platform",
+        userVerification: "required", // or "preferred"
+    },
+    attestation: "none", // Fast & privacy-preserving auth without security compromise
+};
+
+const credential = await navigator.credentials.create({ publicKey: regOptions });
+console.log('Credential details:', credential);
+// Pass credential to server for verification: passcay.register.verify
+
+// Authentication
+const authOptions = {
+  challenge: base64UrlDecode(challenge),
+  rpId: 'example.com',
+  userVerification: 'preferred',
+};
+const assertion = await navigator.credentials.get({ publicKey: authOptions });
+console.log('Assertion details:', assertion);
+// Retrieve public_key from assertion_id that's returned
+// Pass assertion to server for verification: passcay.auth.verify
+```
+
+
+<details>
+
+<summary>JavaScript utils for base64url <-> ArrayBuffer</summary>
+
+```javascript
+// Convert base64url <-> ArrayBuffer
+function base64UrlToBuffer(b64url) {
+  const pad = '='.repeat((4 - (b64url.length % 4)) % 4);
+  const b64 = (b64url + pad).replace(/-/g, '+').replace(/_/g, '/');
+  const bin = atob(b64);
+  const arr = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) arr[i] = bin.charCodeAt(i);
+  return arr.buffer;
+}
+function bufferToBase64Url(buf) {
+  const bytes = new Uint8Array(buf);
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+```
+
+</details>
+
+## Demo
+
+Reference implementations for integrating passcay into your application:
+
+- `demo/register.md` - Registration flow with challenge generation
+- `demo/login.md` - Authentication flow with verification
+
+## See also
+
+For passkey authenticator implementations and library for Zig, check out [Zig-Sec/keylib](https://github.com/Zig-Sec/keylib).
+
+
+ ## Spec references
+
+- [W3C WebAuthn](https://www.w3.org/TR/webauthn/)
+- [FIDO2 Client to Authenticator Protocol (CTAP)](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html)
+
+## License
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2025 [U-Zyn Chua](https://uzyn.com).

build.zig

@@ -0,0 +1,87 @@
+const std = @import("std");
+
+// Although this function looks imperative, note that its job is to
+// declaratively construct a build graph that will be executed by an external
+// runner.
+
+/// Helper function to configure OpenSSL
+/// This function just does basic system library linking since we'll use the native OpenSSL
+fn linkWithOpenSSL(_: *std.Build, step: *std.Build.Step.Compile, target: std.Build.ResolvedTarget) void {
+    // Always link with libc
+    step.linkLibC();
+
+    // Link with OpenSSL libraries
+    step.linkSystemLibrary("crypto");
+    step.linkSystemLibrary("ssl");
+
+    // Add special frameworks for macOS
+    if (target.result.os.tag == .macos) {
+        // step.linkFramework("Security");
+        // step.linkFramework("CoreFoundation");
+    }
+}
+
+pub fn build(b: *std.Build) void {
+    // Standard target options allows the person running `zig build` to choose
+    // what target to build for. Here we do not override the defaults, which
+    // means any target is allowed, and the default is native. Other options
+    // for restricting supported target set are available.
+    const target = b.standardTargetOptions(.{});
+
+    // Standard optimization options allow the person running `zig build` to select
+    // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not
+    // set a preferred release mode, allowing the user to decide how to optimize.
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Add dependencies
+    const zbor_dep = b.dependency("zbor", .{
+        .target = target,
+        .optimize = optimize,
+    });
+    const zbor_mod = zbor_dep.module("zbor");
+
+    // Create and add the passcay module to the build so it can be referenced as a dependency
+    const passcay_mod = b.addModule("passcay", .{
+        .root_source_file = b.path("src/public.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    passcay_mod.addImport("zbor", zbor_mod);
+
+    // Now, we will create a static library based on the module we created above.
+    // This creates a `std.Build.Step.Compile`, which is the build step responsible
+    // for actually invoking the compiler.
+    const lib = b.addLibrary(.{
+        .linkage = .static,
+        .name = "passcay",
+        .root_module = passcay_mod,
+    });
+
+    // Link with OpenSSL dynamically
+    linkWithOpenSSL(b, lib, target);
+
+    // This declares intent for the library to be installed into the standard
+    // location when the user invokes the "install" step (the default step when
+    // running `zig build`).
+    b.installArtifact(lib);
+
+    // Creates a step for unit testing. This only builds the test executable
+    // but does not run it.
+    const lib_unit_tests = b.addTest(.{
+        .root_source_file = b.path("src/test_entry.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    lib_unit_tests.root_module.addImport("zbor", zbor_mod);
+
+    // Link with OpenSSL for tests
+    linkWithOpenSSL(b, lib_unit_tests, target);
+
+    const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests);
+
+    // Similar to creating the run step earlier, this exposes a `test` step to
+    // the `zig build --help` menu, providing a way for the user to request
+    // running the unit tests.
+    const test_step = b.step("test", "Run unit tests");
+    test_step.dependOn(&run_lib_unit_tests.step);
+}

build.zig.zon

@@ -0,0 +1,61 @@
+.{
+    // This is the default name used by packages depending on this one. For
+    // example, when a user runs `zig fetch --save <url>`, this field is used
+    // as the key in the `dependencies` table. Although the user can choose a
+    // different name, most users will stick with this provided value.
+    //
+    // It is redundant to include "zig" in this name because it is already
+    // within the Zig package namespace.
+    .name = .passcay,
+
+    // This is a [Semantic Version](https://semver.org/).
+    // In a future version of Zig it will be used for package deduplication.
+    .version = "0.0.0",
+
+    // Together with name, this represents a globally unique package
+    // identifier. This field is generated by the Zig toolchain when the
+    // package is first created, and then *never changes*. This allows
+    // unambiguous detection of one package being an updated version of
+    // another.
+    //
+    // When forking a Zig project, this id should be regenerated (delete the
+    // field and run `zig build`) if the upstream project is still maintained.
+    // Otherwise, the fork is *hostile*, attempting to take control over the
+    // original project's identity. Thus it is recommended to leave the comment
+    // on the following line intact, so that it shows up in code reviews that
+    // modify the field.
+    .fingerprint = 0x6afaa0c072c64272, // Changing this has security and trust implications.
+
+    // Tracks the earliest Zig version that the package considers to be a
+    // supported use case.
+    .minimum_zig_version = "0.15.0-dev.345+ec2888858",
+
+    // This field is optional.
+    // Each dependency must either provide a `url` and `hash`, or a `path`.
+    // `zig build --fetch` can be used to fetch all dependencies of a package, recursively.
+    // Once all dependencies are fetched, `zig build` no longer requires
+    // internet connectivity.
+    .dependencies = .{
+        .zbor = .{
+            .url = "https://github.com/r4gus/zbor/archive/refs/tags/0.17.2.tar.gz",
+            .hash = "zbor-0.17.0-kr-CoHIkAwCy2WhoS6MgwSvyQsLWzzNy6a7UTHqMPMmO",
+        },
+        // Note: OpenSSL is a system dependency and needs to be installed separately
+    },
+
+    // Specifies the set of files and directories that are included in this package.
+    // Only files and directories listed here are included in the `hash` that
+    // is computed for this package. Only files listed here will remain on disk
+    // when using the zig package manager. As a rule of thumb, one should list
+    // files required for compilation plus any license(s).
+    // Paths are relative to the build root. Use the empty string (`""`) to refer to
+    // the build root itself.
+    // A directory listed here means that all files within, recursively, are included.
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        "demo",
+        "README.md",
+    },
+}