@authn-sh/sdk-node 0.4.0-alpha.1

package/README.md

@@ -0,0 +1,117 @@
+# @authn-sh/sdk-node
+
+Node.js / Edge-runtime backend SDK for [authn.sh](https://authn.sh).
+
+Mirrors [`@authn-sh/sdk-php`](https://github.com/authn-sh/sdk-php) — BAPI resource managers, session-JWT verification, webhook signature verification. The frontend counterpart is [`@authn-sh/sdk-js`](https://github.com/authn-sh/javascript/tree/main/packages/sdk-js).
+
+Runs anywhere `fetch` exists: Node 18+, Cloudflare Workers, Vercel Edge, Bun, Deno.
+
+## Install
+
+```
+npm install @authn-sh/sdk-node
+```
+
+## BAPI client
+
+```ts
+import { Authn } from '@authn-sh/sdk-node';
+
+const authn = new Authn({ secretKey: process.env.AUTHN_SECRET_KEY! });
+
+// Users
+const user = await authn.users.get('user_01HXYZ');
+await authn.users.ban('user_01HXYZ');
+const fresh = await authn.users.create({ first_name: 'Alice', email_addresses: ['alice@example.com'] });
+
+// Sessions
+const session = await authn.sessions.get('sess_01HXYZ');
+const jwt = await authn.sessions.getToken('sess_01HXYZ', 'my-jwt-template');
+
+// Organizations + nested managers
+const org = await authn.organizations.create({ name: 'Acme', slug: 'acme' });
+await authn.organizations.members(org.id).create({ userId: user.id, role: 'org:admin' });
+await authn.organizations.invitations(org.id).create({ email_address: 'bob@acme.com', role: 'org:member' });
+await authn.organizations.domains(org.id).create('acme.com', 'automatic_invitation');
+
+// Social providers + phone numbers + external accounts + SMS templates
+await authn.oauthProviders.list();
+await authn.phoneNumbers.list({ userId: user.id } as any);
+await authn.externalAccounts.list({ userId: user.id } as any);
+await authn.smsTemplates.get('verification_code');
+
+// Instance settings
+const instance = await authn.instance.get();
+await authn.instance.update({ multi_factor: { phone_code: { enabled: true } } });
+```
+
+Errors from the API surface as `AuthnHttpError` (`status`, `code`, `requestId`, `errors[]`).
+
+## Session-JWT verification
+
+```ts
+import { TokenVerifier } from '@authn-sh/sdk-node';
+
+const verifier = new TokenVerifier({ publishableKey: process.env.AUTHN_PUBLISHABLE_KEY! });
+
+// In your auth middleware:
+const cookie = req.cookies['__session'];
+const claims = await verifier.verify(cookie);  // throws AuthnTokenInvalidError on bad token
+
+console.log(claims.sub);                        // user_…
+console.log(claims.organization?.role);         // 'org:admin'
+console.log(claims.hasPermission('org:billing:read'));
+console.log(claims.hasVerifiedPhoneNumber());
+console.log(claims.preferredSecondFactor());    // 'totp' | 'phone_code' | 'backup_code' | null
+```
+
+For "best-effort" auth that falls back to unauthenticated, use `tryVerify()` — returns `null` instead of throwing.
+
+The verifier resolves the FAPI host from the `publishableKey`; pass `frontendApiUrl` explicitly when self-hosting on a custom domain. JWKS is fetched once and cached in memory (default 10 min TTL).
+
+## Webhook signature verification
+
+```ts
+import express from 'express';
+import { WebhookSignatureVerifier } from '@authn-sh/sdk-node';
+
+const app = express();
+const verifier = new WebhookSignatureVerifier({
+  signingSecret: process.env.AUTHN_WEBHOOK_SECRET!,
+});
+
+app.post('/webhooks/authn', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const event = verifier.verify(req.body.toString('utf8'), req.headers);
+    switch (event.type) {
+      case 'user.created':       /* … */; break;
+      case 'phoneNumber.verified': /* … */; break;
+    }
+    res.status(204).end();
+  } catch {
+    res.status(400).end();
+  }
+});
+```
+
+To rotate the signing secret without downtime, pass an array — the verifier accepts a request if any provided signature matches any secret:
+
+```ts
+new WebhookSignatureVerifier({ signingSecret: [oldSecret, newSecret] });
+```
+
+## Runtime support
+
+| Runtime           | Status                                       |
+| ----------------- | -------------------------------------------- |
+| Node.js 18+       | ✓ first-class                                |
+| Cloudflare Workers | ✓ (uses `globalThis.fetch` + `node:crypto`) |
+| Vercel Edge       | ✓                                            |
+| Bun               | ✓                                            |
+| Deno              | ✓ via `npm:` specifier                       |
+
+The webhook verifier imports `node:crypto`. On edge runtimes that polyfill it (Workers, Vercel Edge), no action is needed.
+
+## License
+
+AGPL-3.0-only — see [LICENSE](./LICENSE). For commercially licensed deployments, contact [authn.sh](https://authn.sh).

package/dist/errors.cjs

@@ -0,0 +1,45 @@
+'use strict';
+
+// src/errors/index.ts
+var AuthnHttpError = class extends Error {
+  constructor(status, errors, requestId, message) {
+    super(message ?? (errors[0]?.longMessage || errors[0]?.message) ?? `authn.sh API returned HTTP ${status}`);
+    this.status = status;
+    this.errors = errors;
+    this.requestId = requestId;
+  }
+  status;
+  errors;
+  requestId;
+  name = "AuthnHttpError";
+  /** The primary error code returned by the API (when present). */
+  get code() {
+    return this.errors[0]?.code ?? null;
+  }
+};
+var AuthnConfigError = class extends Error {
+  name = "AuthnConfigError";
+};
+var AuthnTokenInvalidError = class extends Error {
+  constructor(reason, message) {
+    super(message ?? `Token invalid: ${reason}`);
+    this.reason = reason;
+  }
+  reason;
+  name = "AuthnTokenInvalidError";
+};
+var AuthnWebhookSignatureInvalidError = class extends Error {
+  constructor(reason, message) {
+    super(message ?? `Webhook signature invalid: ${reason}`);
+    this.reason = reason;
+  }
+  reason;
+  name = "AuthnWebhookSignatureInvalidError";
+};
+
+exports.AuthnConfigError = AuthnConfigError;
+exports.AuthnHttpError = AuthnHttpError;
+exports.AuthnTokenInvalidError = AuthnTokenInvalidError;
+exports.AuthnWebhookSignatureInvalidError = AuthnWebhookSignatureInvalidError;
+//# sourceMappingURL=errors.cjs.map
+//# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/index.ts"],"names":[],"mappings":";;;AAaO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAGxC,WAAA,CACkB,MAAA,EACA,MAAA,EACA,SAAA,EAChB,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,KAAY,MAAA,CAAO,CAAC,CAAA,EAAG,WAAA,IAAe,MAAA,CAAO,CAAC,CAAA,EAAG,OAAA,CAAA,IAAY,CAAA,2BAAA,EAA8B,MAAM,CAAA,CAAE,CAAA;AALzF,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AAAA,EAIlB;AAAA,EANkB,MAAA;AAAA,EACA,MAAA;AAAA,EACA,SAAA;AAAA,EALO,IAAA,GAAM,gBAAA;AAAA;AAAA,EAY/B,IAAI,IAAA,GAAsB;AACxB,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA,EAAG,IAAA,IAAQ,IAAA;AAAA,EACjC;AACF;AAKO,IAAM,gBAAA,GAAN,cAA+B,KAAA,CAAM;AAAA,EACjB,IAAA,GAAM,kBAAA;AACjC;AAMO,IAAM,sBAAA,GAAN,cAAqC,KAAA,CAAM;AAAA,EAGhD,WAAA,CACkB,QAShB,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,IAAW,CAAA,eAAA,EAAkB,MAAM,CAAA,CAAE,CAAA;AAX3B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAYlB;AAAA,EAZkB,MAAA;AAAA,EAHO,IAAA,GAAM,wBAAA;AAgBjC;AAKO,IAAM,iCAAA,GAAN,cAAgD,KAAA,CAAM;AAAA,EAG3D,WAAA,CACkB,QAMhB,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,IAAW,CAAA,2BAAA,EAA8B,MAAM,CAAA,CAAE,CAAA;AARvC,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EASlB;AAAA,EATkB,MAAA;AAAA,EAHO,IAAA,GAAM,mCAAA;AAajC","file":"errors.cjs","sourcesContent":["/**\n * Error shape emitted by the authn.sh API.\n */\nexport interface AuthnApiError {\n  code: string;\n  message: string;\n  longMessage?: string;\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Thrown when a request to the BAPI returns a non-2xx response.\n */\nexport class AuthnHttpError extends Error {\n  public override readonly name ='AuthnHttpError';\n\n  constructor(\n    public readonly status: number,\n    public readonly errors: AuthnApiError[],\n    public readonly requestId: string | null,\n    message?: string,\n  ) {\n    super(message ?? (errors[0]?.longMessage || errors[0]?.message) ?? `authn.sh API returned HTTP ${status}`);\n  }\n\n  /** The primary error code returned by the API (when present). */\n  get code(): string | null {\n    return this.errors[0]?.code ?? null;\n  }\n}\n\n/**\n * Thrown when the SDK is misconfigured (missing secret key, malformed URL, etc.).\n */\nexport class AuthnConfigError extends Error {\n  public override readonly name ='AuthnConfigError';\n}\n\n/**\n * Thrown when a JWT can't be verified — wrong signature, expired, malformed,\n * issuer mismatch, etc. The `reason` discriminates between the failure modes.\n */\nexport class AuthnTokenInvalidError extends Error {\n  public override readonly name ='AuthnTokenInvalidError';\n\n  constructor(\n    public readonly reason:\n      | 'malformed'\n      | 'signature_invalid'\n      | 'expired'\n      | 'not_yet_valid'\n      | 'issuer_mismatch'\n      | 'audience_mismatch'\n      | 'key_not_found'\n      | 'jwks_fetch_failed',\n    message?: string,\n  ) {\n    super(message ?? `Token invalid: ${reason}`);\n  }\n}\n\n/**\n * Thrown when a webhook signature can't be verified.\n */\nexport class AuthnWebhookSignatureInvalidError extends Error {\n  public override readonly name ='AuthnWebhookSignatureInvalidError';\n\n  constructor(\n    public readonly reason:\n      | 'missing_signature_header'\n      | 'malformed_signature_header'\n      | 'no_matching_signature'\n      | 'timestamp_too_old'\n      | 'timestamp_missing',\n    message?: string,\n  ) {\n    super(message ?? `Webhook signature invalid: ${reason}`);\n  }\n}\n"]}

package/dist/errors.d.cts

@@ -0,0 +1,46 @@
+/**
+ * Error shape emitted by the authn.sh API.
+ */
+interface AuthnApiError {
+    code: string;
+    message: string;
+    longMessage?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Thrown when a request to the BAPI returns a non-2xx response.
+ */
+declare class AuthnHttpError extends Error {
+    readonly status: number;
+    readonly errors: AuthnApiError[];
+    readonly requestId: string | null;
+    readonly name = "AuthnHttpError";
+    constructor(status: number, errors: AuthnApiError[], requestId: string | null, message?: string);
+    /** The primary error code returned by the API (when present). */
+    get code(): string | null;
+}
+/**
+ * Thrown when the SDK is misconfigured (missing secret key, malformed URL, etc.).
+ */
+declare class AuthnConfigError extends Error {
+    readonly name = "AuthnConfigError";
+}
+/**
+ * Thrown when a JWT can't be verified — wrong signature, expired, malformed,
+ * issuer mismatch, etc. The `reason` discriminates between the failure modes.
+ */
+declare class AuthnTokenInvalidError extends Error {
+    readonly reason: 'malformed' | 'signature_invalid' | 'expired' | 'not_yet_valid' | 'issuer_mismatch' | 'audience_mismatch' | 'key_not_found' | 'jwks_fetch_failed';
+    readonly name = "AuthnTokenInvalidError";
+    constructor(reason: 'malformed' | 'signature_invalid' | 'expired' | 'not_yet_valid' | 'issuer_mismatch' | 'audience_mismatch' | 'key_not_found' | 'jwks_fetch_failed', message?: string);
+}
+/**
+ * Thrown when a webhook signature can't be verified.
+ */
+declare class AuthnWebhookSignatureInvalidError extends Error {
+    readonly reason: 'missing_signature_header' | 'malformed_signature_header' | 'no_matching_signature' | 'timestamp_too_old' | 'timestamp_missing';
+    readonly name = "AuthnWebhookSignatureInvalidError";
+    constructor(reason: 'missing_signature_header' | 'malformed_signature_header' | 'no_matching_signature' | 'timestamp_too_old' | 'timestamp_missing', message?: string);
+}
+
+export { type AuthnApiError, AuthnConfigError, AuthnHttpError, AuthnTokenInvalidError, AuthnWebhookSignatureInvalidError };

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Error shape emitted by the authn.sh API.
+ */
+interface AuthnApiError {
+    code: string;
+    message: string;
+    longMessage?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * Thrown when a request to the BAPI returns a non-2xx response.
+ */
+declare class AuthnHttpError extends Error {
+    readonly status: number;
+    readonly errors: AuthnApiError[];
+    readonly requestId: string | null;
+    readonly name = "AuthnHttpError";
+    constructor(status: number, errors: AuthnApiError[], requestId: string | null, message?: string);
+    /** The primary error code returned by the API (when present). */
+    get code(): string | null;
+}
+/**
+ * Thrown when the SDK is misconfigured (missing secret key, malformed URL, etc.).
+ */
+declare class AuthnConfigError extends Error {
+    readonly name = "AuthnConfigError";
+}
+/**
+ * Thrown when a JWT can't be verified — wrong signature, expired, malformed,
+ * issuer mismatch, etc. The `reason` discriminates between the failure modes.
+ */
+declare class AuthnTokenInvalidError extends Error {
+    readonly reason: 'malformed' | 'signature_invalid' | 'expired' | 'not_yet_valid' | 'issuer_mismatch' | 'audience_mismatch' | 'key_not_found' | 'jwks_fetch_failed';
+    readonly name = "AuthnTokenInvalidError";
+    constructor(reason: 'malformed' | 'signature_invalid' | 'expired' | 'not_yet_valid' | 'issuer_mismatch' | 'audience_mismatch' | 'key_not_found' | 'jwks_fetch_failed', message?: string);
+}
+/**
+ * Thrown when a webhook signature can't be verified.
+ */
+declare class AuthnWebhookSignatureInvalidError extends Error {
+    readonly reason: 'missing_signature_header' | 'malformed_signature_header' | 'no_matching_signature' | 'timestamp_too_old' | 'timestamp_missing';
+    readonly name = "AuthnWebhookSignatureInvalidError";
+    constructor(reason: 'missing_signature_header' | 'malformed_signature_header' | 'no_matching_signature' | 'timestamp_too_old' | 'timestamp_missing', message?: string);
+}
+
+export { type AuthnApiError, AuthnConfigError, AuthnHttpError, AuthnTokenInvalidError, AuthnWebhookSignatureInvalidError };

package/dist/errors.js

@@ -0,0 +1,40 @@
+// src/errors/index.ts
+var AuthnHttpError = class extends Error {
+  constructor(status, errors, requestId, message) {
+    super(message ?? (errors[0]?.longMessage || errors[0]?.message) ?? `authn.sh API returned HTTP ${status}`);
+    this.status = status;
+    this.errors = errors;
+    this.requestId = requestId;
+  }
+  status;
+  errors;
+  requestId;
+  name = "AuthnHttpError";
+  /** The primary error code returned by the API (when present). */
+  get code() {
+    return this.errors[0]?.code ?? null;
+  }
+};
+var AuthnConfigError = class extends Error {
+  name = "AuthnConfigError";
+};
+var AuthnTokenInvalidError = class extends Error {
+  constructor(reason, message) {
+    super(message ?? `Token invalid: ${reason}`);
+    this.reason = reason;
+  }
+  reason;
+  name = "AuthnTokenInvalidError";
+};
+var AuthnWebhookSignatureInvalidError = class extends Error {
+  constructor(reason, message) {
+    super(message ?? `Webhook signature invalid: ${reason}`);
+    this.reason = reason;
+  }
+  reason;
+  name = "AuthnWebhookSignatureInvalidError";
+};
+
+export { AuthnConfigError, AuthnHttpError, AuthnTokenInvalidError, AuthnWebhookSignatureInvalidError };
+//# sourceMappingURL=errors.js.map
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/index.ts"],"names":[],"mappings":";AAaO,IAAM,cAAA,GAAN,cAA6B,KAAA,CAAM;AAAA,EAGxC,WAAA,CACkB,MAAA,EACA,MAAA,EACA,SAAA,EAChB,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,KAAY,MAAA,CAAO,CAAC,CAAA,EAAG,WAAA,IAAe,MAAA,CAAO,CAAC,CAAA,EAAG,OAAA,CAAA,IAAY,CAAA,2BAAA,EAA8B,MAAM,CAAA,CAAE,CAAA;AALzF,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AACA,IAAA,IAAA,CAAA,SAAA,GAAA,SAAA;AAAA,EAIlB;AAAA,EANkB,MAAA;AAAA,EACA,MAAA;AAAA,EACA,SAAA;AAAA,EALO,IAAA,GAAM,gBAAA;AAAA;AAAA,EAY/B,IAAI,IAAA,GAAsB;AACxB,IAAA,OAAO,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA,EAAG,IAAA,IAAQ,IAAA;AAAA,EACjC;AACF;AAKO,IAAM,gBAAA,GAAN,cAA+B,KAAA,CAAM;AAAA,EACjB,IAAA,GAAM,kBAAA;AACjC;AAMO,IAAM,sBAAA,GAAN,cAAqC,KAAA,CAAM;AAAA,EAGhD,WAAA,CACkB,QAShB,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,IAAW,CAAA,eAAA,EAAkB,MAAM,CAAA,CAAE,CAAA;AAX3B,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EAYlB;AAAA,EAZkB,MAAA;AAAA,EAHO,IAAA,GAAM,wBAAA;AAgBjC;AAKO,IAAM,iCAAA,GAAN,cAAgD,KAAA,CAAM;AAAA,EAG3D,WAAA,CACkB,QAMhB,OAAA,EACA;AACA,IAAA,KAAA,CAAM,OAAA,IAAW,CAAA,2BAAA,EAA8B,MAAM,CAAA,CAAE,CAAA;AARvC,IAAA,IAAA,CAAA,MAAA,GAAA,MAAA;AAAA,EASlB;AAAA,EATkB,MAAA;AAAA,EAHO,IAAA,GAAM,mCAAA;AAajC","file":"errors.js","sourcesContent":["/**\n * Error shape emitted by the authn.sh API.\n */\nexport interface AuthnApiError {\n  code: string;\n  message: string;\n  longMessage?: string;\n  meta?: Record<string, unknown>;\n}\n\n/**\n * Thrown when a request to the BAPI returns a non-2xx response.\n */\nexport class AuthnHttpError extends Error {\n  public override readonly name ='AuthnHttpError';\n\n  constructor(\n    public readonly status: number,\n    public readonly errors: AuthnApiError[],\n    public readonly requestId: string | null,\n    message?: string,\n  ) {\n    super(message ?? (errors[0]?.longMessage || errors[0]?.message) ?? `authn.sh API returned HTTP ${status}`);\n  }\n\n  /** The primary error code returned by the API (when present). */\n  get code(): string | null {\n    return this.errors[0]?.code ?? null;\n  }\n}\n\n/**\n * Thrown when the SDK is misconfigured (missing secret key, malformed URL, etc.).\n */\nexport class AuthnConfigError extends Error {\n  public override readonly name ='AuthnConfigError';\n}\n\n/**\n * Thrown when a JWT can't be verified — wrong signature, expired, malformed,\n * issuer mismatch, etc. The `reason` discriminates between the failure modes.\n */\nexport class AuthnTokenInvalidError extends Error {\n  public override readonly name ='AuthnTokenInvalidError';\n\n  constructor(\n    public readonly reason:\n      | 'malformed'\n      | 'signature_invalid'\n      | 'expired'\n      | 'not_yet_valid'\n      | 'issuer_mismatch'\n      | 'audience_mismatch'\n      | 'key_not_found'\n      | 'jwks_fetch_failed',\n    message?: string,\n  ) {\n    super(message ?? `Token invalid: ${reason}`);\n  }\n}\n\n/**\n * Thrown when a webhook signature can't be verified.\n */\nexport class AuthnWebhookSignatureInvalidError extends Error {\n  public override readonly name ='AuthnWebhookSignatureInvalidError';\n\n  constructor(\n    public readonly reason:\n      | 'missing_signature_header'\n      | 'malformed_signature_header'\n      | 'no_matching_signature'\n      | 'timestamp_too_old'\n      | 'timestamp_missing',\n    message?: string,\n  ) {\n    super(message ?? `Webhook signature invalid: ${reason}`);\n  }\n}\n"]}