@productcraft/auth 0.6.0 → 0.7.1

package/README.md

@@ -217,6 +217,56 @@ await consumer.auth.signinWithProvider({
 
 No SDK upgrade required — the per-provider TS enum widens automatically with the next spec refresh.
 
+## Passkeys (WebAuthn)
+
+Passkeys are switched on per app in the console (relying-party id + the
+site origin in `allowed_redirect_origins`). Once they are, each ceremony
+is one call on `auth.consumer(appSlug).passkeys`. The helpers run
+**in the browser** — they drive `navigator.credentials` — but importing
+the package anywhere is safe; nothing touches a browser global until you
+call them.
+
+```ts
+import { Auth, isPasskeySupported, PasskeyError } from "@productcraft/auth";
+
+if (!isPasskeySupported()) hidePasskeyButton(); // false in Node and in insecure contexts
+
+// Enrol — signed-in user adds a passkey as an MFA factor
+const me = new Auth({ auth: { type: "bearer", token: accessToken } }).consumer("acme");
+const { factor, recovery_codes } = await me.passkeys.enroll({ label: "MacBook" });
+// show recovery_codes once — they are not retrievable later
+
+// Passwordless sign-in — no password, no email; discoverable credential
+const anon = new Auth().consumer("acme");
+const session = await anon.passkeys.signIn({ mediation: "conditional" }); // amr: ["webauthn"]
+
+// MFA step of a password sign-in — when signin() answered { mfa_required, mfa_token, factors }
+const session2 = await anon.passkeys.completeMfaChallenge({ mfa_token: signin.mfa_token });
+
+// Step-up inside a live session
+const { amr, mfa_at } = await me.passkeys.stepUp();
+```
+
+Each helper does the options call → `navigator.credentials.create()` /
+`.get()` → verify call, with every buffer base64url-encoded in both
+directions and the `public_key` members renamed to the WebAuthn spec's
+camelCase (the Auth wire is snake_case). Browser-side failures reject
+with `PasskeyError` (`code`: `unsupported`, `cancelled`, `timeout`,
+`invalid_state`, `security`, `no_credential`, `unknown`; `cause` holds
+the DOM error); server-side failures stay `AuthHttpError`, so a 401 on
+a forged or replayed assertion is distinguishable from the user
+dismissing the prompt. Pass `signal: AbortSignal.timeout(ms)` to bound
+the prompt yourself.
+
+The encoding layer is exported for anyone who wants the pieces:
+`toB64u`, `fromB64u`, `decodeOptions`, `encodeCredential`, plus
+`createPasskeyCredential(public_key)` / `getPasskeyCredential(public_key)`
+which wrap `navigator.credentials` on their own.
+
+`signIn()` never sends an identifier: `/auth/passkey/options` takes none
+by design (it would be an account-existence oracle), so sign-in relies on
+a discoverable (resident) credential.
+
 ## JWT verification
 
 Every Auth app publishes a JWKS at `/{appSlug}/v1/.well-known/jwks.json`. The SDK gives you a verified-claims helper and a jose-compatible JWKS resolver.
@@ -279,7 +329,7 @@ For the per-app boundary, the JWKS is the cryptographic gate (only the app's key
 
 ### Passport integration
 
-Use the companion package [`@productcraft/auth-passport`](../auth-passport):
+Use the companion package [`@productcraft/auth-passport`](https://github.com/clauderanelagh/productcraft-node/tree/main/packages/auth-passport):
 
 ```bash
 npm install @productcraft/auth-passport passport-jwt
@@ -343,4 +393,4 @@ When the spec changes, the nightly `spec-refresh` workflow re-runs codegen and o
 
 ## License
 
-[MIT](../../LICENSE).
+[MIT](https://github.com/clauderanelagh/productcraft-node/blob/main/LICENSE).

package/dist/index.cjs

@@ -765,11 +765,15 @@ function getApiKeyControllerListApiKeysUrl({
   const res = { method: "GET", url: `/v1/apps/${app_id}/api-keys` };
   return res;
 }
-async function apiKeyControllerListApiKeys({ appId }, config = {}) {
+async function apiKeyControllerListApiKeys({
+  appId,
+  params
+}, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const res = await request({
     method: "GET",
     url: getApiKeyControllerListApiKeysUrl({ appId }).url.toString(),
+    params,
     ...requestConfig
   });
   return res.data;
@@ -1031,7 +1035,9 @@ async function appAuditControllerGetAuditLogs({
     limit: params.limit,
     cursor: params.cursor,
     action: params.action,
-    actor_id: params.actorId
+    actor_id: params.actorId,
+    since: params.since,
+    until: params.until
   } : void 0;
   const res = await request({
     method: "GET",
@@ -1557,6 +1563,220 @@ async function consumerIdpControllerNativeSignIn({
   return res.data;
 }
 
+// src/_generated/clients/consumerAuth/consumerAuthControllerPasskeyOptions.ts
+function getConsumerAuthControllerPasskeyOptionsUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/auth/passkey/options`
+  };
+  return res;
+}
+async function consumerAuthControllerPasskeyOptions({
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerAuthControllerPasskeyOptionsUrl({ appSlug }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerAuth/consumerAuthControllerPasskeyVerify.ts
+function getConsumerAuthControllerPasskeyVerifyUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/auth/passkey/verify`
+  };
+  return res;
+}
+async function consumerAuthControllerPasskeyVerify({
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerAuthControllerPasskeyVerifyUrl({ appSlug }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerAuth/consumerAuthControllerMfaWebauthnOptions.ts
+function getConsumerAuthControllerMfaWebauthnOptionsUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/auth/mfa/webauthn/options`
+  };
+  return res;
+}
+async function consumerAuthControllerMfaWebauthnOptions({
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerAuthControllerMfaWebauthnOptionsUrl({
+      appSlug
+    }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerAuth/consumerAuthControllerMfaVerify.ts
+function getConsumerAuthControllerMfaVerifyUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/auth/mfa/verify`
+  };
+  return res;
+}
+async function consumerAuthControllerMfaVerify({
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerAuthControllerMfaVerifyUrl({ appSlug }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerMfa/consumerMfaControllerStartEnrollment.ts
+function getConsumerMfaControllerStartEnrollmentUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/me/mfa/factors`
+  };
+  return res;
+}
+async function consumerMfaControllerStartEnrollment({
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerMfaControllerStartEnrollmentUrl({ appSlug }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerMfa/consumerMfaControllerConfirmEnrollment.ts
+function getConsumerMfaControllerConfirmEnrollmentUrl({
+  id,
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/me/mfa/factors/${id}/verify`
+  };
+  return res;
+}
+async function consumerMfaControllerConfirmEnrollment({
+  id,
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerMfaControllerConfirmEnrollmentUrl({
+      id,
+      appSlug
+    }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerMfa/consumerMfaControllerStepUpWebauthnOptions.ts
+function getConsumerMfaControllerStepUpWebauthnOptionsUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/me/mfa/step-up/webauthn/options`
+  };
+  return res;
+}
+async function consumerMfaControllerStepUpWebauthnOptions({
+  appSlug
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const res = await request({
+    method: "POST",
+    url: getConsumerMfaControllerStepUpWebauthnOptionsUrl({
+      appSlug
+    }).url.toString(),
+    ...requestConfig
+  });
+  return res.data;
+}
+
+// src/_generated/clients/consumerMfa/consumerMfaControllerStepUp.ts
+function getConsumerMfaControllerStepUpUrl({
+  appSlug
+}) {
+  const app_slug = appSlug;
+  const res = {
+    method: "POST",
+    url: `/${app_slug}/v1/me/mfa/step-up`
+  };
+  return res;
+}
+async function consumerMfaControllerStepUp({
+  appSlug,
+  data
+}, config = {}) {
+  const { client: request = client, ...requestConfig } = config;
+  const requestData = data;
+  const res = await request({
+    method: "POST",
+    url: getConsumerMfaControllerStepUpUrl({ appSlug }).url.toString(),
+    data: requestData,
+    ...requestConfig
+  });
+  return res.data;
+}
+
 // src/_generated/clients/consumerVerify/consumerVerifyControllerVerify.ts
 function getConsumerVerifyControllerVerifyUrl({
   appSlug
@@ -1662,6 +1882,165 @@ async function consumerOAuthControllerClientCredentials({
   return res.data;
 }
 
+// src/passkeys.ts
+function toB64u(buf) {
+  const bytes = buf instanceof ArrayBuffer ? new Uint8Array(buf) : new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+  let bin = "";
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64u(s) {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(b64.padEnd(Math.ceil(b64.length / 4) * 4, "="));
+  return Uint8Array.from(bin, (c) => c.charCodeAt(0));
+}
+var snakeToCamel = (k) => k.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+function camelizeKeys(value) {
+  if (Array.isArray(value)) return value.map(camelizeKeys);
+  if (value && typeof value === "object" && !(value instanceof Uint8Array)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[snakeToCamel(k)] = camelizeKeys(v);
+    }
+    return out;
+  }
+  return value;
+}
+function decodeOptions(publicKey) {
+  const pk = camelizeKeys(publicKey);
+  const out = {
+    ...pk,
+    challenge: fromB64u(pk.challenge)
+  };
+  if (pk.user) {
+    out.user = { ...pk.user, id: fromB64u(pk.user.id) };
+  }
+  for (const list of ["excludeCredentials", "allowCredentials"]) {
+    const entries = pk[list];
+    if (entries) {
+      out[list] = entries.map((c) => ({ ...c, id: fromB64u(c.id) }));
+    }
+  }
+  return out;
+}
+function encodeCredential(cred) {
+  const r = cred.response;
+  const response = {
+    clientDataJSON: toB64u(r.clientDataJSON)
+  };
+  if (r.attestationObject) response.attestationObject = toB64u(r.attestationObject);
+  if (r.authenticatorData) response.authenticatorData = toB64u(r.authenticatorData);
+  if (r.signature) response.signature = toB64u(r.signature);
+  if (r.userHandle) response.userHandle = toB64u(r.userHandle);
+  return { id: cred.id, response };
+}
+var PasskeyError = class extends Error {
+  code;
+  cause;
+  constructor(code, message, cause) {
+    super(message);
+    this.name = "PasskeyError";
+    this.code = code;
+    this.cause = cause;
+  }
+};
+function browserCredentials() {
+  const nav = globalThis.navigator;
+  const creds = nav?.credentials;
+  if (!creds || typeof creds.create !== "function" || typeof creds.get !== "function") {
+    return void 0;
+  }
+  return creds;
+}
+function isPasskeySupported() {
+  const g = globalThis;
+  if (typeof g.window === "undefined") return false;
+  if (typeof g.PublicKeyCredential !== "function") return false;
+  if (g.isSecureContext === false) return false;
+  return browserCredentials() !== void 0;
+}
+function mapDomError(err) {
+  const name = err?.name;
+  const message = err?.message ?? String(err);
+  switch (name) {
+    case "NotAllowedError":
+      return new PasskeyError(
+        "cancelled",
+        `Passkey prompt was cancelled, timed out, or no passkey matched: ${message}`,
+        err
+      );
+    case "InvalidStateError":
+      return new PasskeyError("invalid_state", `Authenticator refused: ${message}`, err);
+    case "SecurityError":
+      return new PasskeyError(
+        "security",
+        `Page origin does not match the app's rp_id: ${message}`,
+        err
+      );
+    case "AbortError":
+      return new PasskeyError("cancelled", `Passkey ceremony aborted: ${message}`, err);
+    case "TimeoutError":
+      return new PasskeyError(
+        "timeout",
+        `Passkey prompt timed out before a credential was produced: ${message}`,
+        err
+      );
+    default:
+      return new PasskeyError("unknown", `navigator.credentials failed: ${message}`, err);
+  }
+}
+function resolveCredentials(opts = {}) {
+  const creds = opts.credentials ?? browserCredentials();
+  if (!creds) {
+    throw new PasskeyError(
+      "unsupported",
+      "navigator.credentials is not available \u2014 passkeys need a browser with WebAuthn (check isPasskeySupported())"
+    );
+  }
+  return creds;
+}
+function isCredentialLike(value) {
+  if (!value || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.id === "string" && !!v.response && typeof v.response === "object";
+}
+async function createPasskeyCredential(publicKey, opts = {}) {
+  const creds = resolveCredentials(opts);
+  let cred;
+  try {
+    cred = await creds.create({ publicKey: decodeOptions(publicKey), signal: opts.signal });
+  } catch (err) {
+    throw mapDomError(err);
+  }
+  if (!isCredentialLike(cred)) {
+    throw new PasskeyError(
+      "no_credential",
+      "navigator.credentials.create() returned no usable credential"
+    );
+  }
+  return encodeCredential(cred);
+}
+async function getPasskeyCredential(publicKey, opts = {}) {
+  const creds = resolveCredentials(opts);
+  let cred;
+  try {
+    cred = await creds.get({
+      publicKey: decodeOptions(publicKey),
+      mediation: opts.mediation,
+      signal: opts.signal
+    });
+  } catch (err) {
+    throw mapDomError(err);
+  }
+  if (!isCredentialLike(cred)) {
+    throw new PasskeyError(
+      "no_credential",
+      "navigator.credentials.get() returned no usable credential"
+    );
+  }
+  return encodeCredential(cred);
+}
+
 // src/jwt/errors.ts
 var JwtVerifyError = class extends Error {
   code;
@@ -2116,6 +2495,141 @@ var ConsumerScope = class {
     )
   };
   // ─────────────────────────────────────────────────────────────
+  // Passkeys — WebAuthn ceremonies, one call each. BROWSER ONLY at
+  // call time (they drive navigator.credentials); importing is safe
+  // anywhere. Base64url in both directions is handled here; the
+  // wire stays snake_case except the spec-fixed response members
+  // (clientDataJSON, attestationObject, authenticatorData, signature,
+  // userHandle), which travel verbatim.
+  // ─────────────────────────────────────────────────────────────
+  passkeys = {
+    /**
+     * Enrol a passkey as an MFA factor for the signed-in end-user.
+     * Requires the scope to carry the user's access token
+     * (`new Auth({ auth: { type: "bearer", token } })`).
+     *
+     * `POST /me/mfa/factors { type: "webauthn" }` →
+     * `navigator.credentials.create()` →
+     * `POST /me/mfa/factors/:id/verify { credential }`.
+     *
+     * Resolves with the now-enabled factor and the user's recovery
+     * codes — show those once, they are not retrievable later. The
+     * factor stays disabled until the verify call succeeds, so an
+     * abandoned prompt leaves nothing usable behind.
+     */
+    enroll: async (opts = {}) => {
+      const credentials = resolveCredentials(opts);
+      const start = await consumerMfaControllerStartEnrollment(
+        {
+          appSlug: this.appSlug,
+          data: { type: "webauthn", ...opts.label ? { label: opts.label } : {} }
+        },
+        { client: this.client }
+      );
+      const publicKey = start.enrollment.public_key;
+      const credential = await createPasskeyCredential(publicKey, { ...opts, credentials });
+      return await consumerMfaControllerConfirmEnrollment(
+        { appSlug: this.appSlug, id: start.factor.id, data: { credential } },
+        { client: this.client }
+      );
+    },
+    /**
+     * Passwordless sign-in with a discoverable passkey. No password,
+     * no email address: the authenticator finds its own passkey for
+     * the app's rp_id.
+     *
+     * `POST /auth/passkey/options {}` → `navigator.credentials.get()`
+     * → `POST /auth/passkey/verify { credential }`.
+     *
+     * Resolves with the session (`access_token`, `refresh_token`,
+     * …; `amr: ["webauthn"]`). Rejects with `PasskeyError`
+     * (`code: "cancelled"`) when the user dismisses the prompt or no
+     * passkey matches, and with `AuthHttpError` 401 for a forged,
+     * unknown, replayed or expired assertion — the server answers
+     * those uniformly on purpose.
+     *
+     * The options call deliberately takes no identifier (it would be
+     * an account-existence oracle); `tenant_id` is the only
+     * accepted body member and only matters for multi-tenant apps.
+     * Pass `mediation: "conditional"` for autofill-style UI.
+     */
+    signIn: async (opts = {}) => {
+      const credentials = resolveCredentials(opts);
+      const { public_key } = await consumerAuthControllerPasskeyOptions(
+        {
+          appSlug: this.appSlug,
+          data: opts.tenant_id ? { tenant_id: opts.tenant_id } : {}
+        },
+        { client: this.client }
+      );
+      const credential = await getPasskeyCredential(
+        public_key,
+        { ...opts, credentials }
+      );
+      return await consumerAuthControllerPasskeyVerify(
+        { appSlug: this.appSlug, data: { credential } },
+        { client: this.client }
+      );
+    },
+    /**
+     * Satisfy the MFA step of a password sign-in with a passkey.
+     * Call it when `auth.signin()` answered
+     * `{ mfa_required: true, mfa_token, factors }` and `factors`
+     * contains a `webauthn` entry.
+     *
+     * `POST /auth/mfa/webauthn/options { mfa_token }` →
+     * `navigator.credentials.get()` →
+     * `POST /auth/mfa/verify { mfa_token, credential }`.
+     *
+     * Resolves with the session (`amr: ["pwd", "webauthn"]`, fresh
+     * `mfa_at`). Possession of the `mfa_token` — a correct password
+     * — is the authority for the options call.
+     */
+    completeMfaChallenge: async (args) => {
+      const { mfa_token, ...browserOpts } = args;
+      const credentials = resolveCredentials(browserOpts);
+      const { public_key } = await consumerAuthControllerMfaWebauthnOptions(
+        { appSlug: this.appSlug, data: { mfa_token } },
+        { client: this.client }
+      );
+      const credential = await getPasskeyCredential(
+        public_key,
+        { ...browserOpts, credentials }
+      );
+      return await consumerAuthControllerMfaVerify(
+        { appSlug: this.appSlug, data: { mfa_token, credential } },
+        { client: this.client }
+      );
+    },
+    /**
+     * Re-confirm the signed-in user's identity inside a live session
+     * (before a sensitive action). Requires the scope to carry the
+     * user's access token.
+     *
+     * `POST /me/mfa/step-up/webauthn/options` →
+     * `navigator.credentials.get()` →
+     * `POST /me/mfa/step-up { credential }`.
+     *
+     * Resolves with `{ amr, mfa_at }`. A passkey assertion is never
+     * tried as a recovery code, so a failed step-up never burns one.
+     */
+    stepUp: async (opts = {}) => {
+      const credentials = resolveCredentials(opts);
+      const { public_key } = await consumerMfaControllerStepUpWebauthnOptions(
+        { appSlug: this.appSlug },
+        { client: this.client }
+      );
+      const credential = await getPasskeyCredential(
+        public_key,
+        { ...opts, credentials }
+      );
+      return await consumerMfaControllerStepUp(
+        { appSlug: this.appSlug, data: { credential } },
+        { client: this.client }
+      );
+    }
+  };
+  // ─────────────────────────────────────────────────────────────
   // OAuth M2M — client_credentials grant for service-to-service tokens
   // ─────────────────────────────────────────────────────────────
   oauth = {
@@ -2134,9 +2648,9 @@ function getAppControllerListMyAppsUrl() {
 async function appControllerListMyApps({ params } = {}, config = {}) {
   const { client: request = client, ...requestConfig } = config;
   const mappedParams = params ? {
+    workspace_id: params.workspaceId,
     limit: params.limit,
-    cursor: params.cursor,
-    workspace_id: params.workspaceId
+    cursor: params.cursor
   } : void 0;
   const res = await request({
     method: "GET",
@@ -2273,6 +2787,14 @@ exports.JwtInvalidError = JwtInvalidError;
 exports.JwtIssuerMismatchError = JwtIssuerMismatchError;
 exports.JwtNotYetValidError = JwtNotYetValidError;
 exports.JwtVerifyError = JwtVerifyError;
+exports.PasskeyError = PasskeyError;
+exports.createPasskeyCredential = createPasskeyCredential;
+exports.decodeOptions = decodeOptions;
+exports.encodeCredential = encodeCredential;
+exports.fromB64u = fromB64u;
+exports.getPasskeyCredential = getPasskeyCredential;
+exports.isPasskeySupported = isPasskeySupported;
+exports.toB64u = toB64u;
 exports.verifyAuthToken = verifyAuthToken;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map