@atlasauth/backend 0.14.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @atlasauth/backend changelog
 
+## 0.16.0 — 2026-10-24
+
+### Added
+
+- `actionGallery` (`list`, `get`, `install`, `installs`, `update`) and `actionTemplates` (`list`, `create`, `get`, `update`, `delete`, `addVersion`, `submitVersion`, `deleteVersion`, `publish`, `unlist`) for the Actions gallery.
+- `ActionTestResult.http_requests` (what `api.http` queued in a dry run) and `organizations` / `country` on the sample event.
+- DPoP server nonces (RFC 9449 §8) in `createAccessTokenVerifier`: `dpopNonces` requires every DPoP proof to carry a nonce the API issued, answering `use_dpop_nonce` with a fresh nonce otherwise; every result carries `dpopNonce` for the `DPoP-Nonce` response header. `memoryDpopNonceSource()` (one process) and `hmacDpopNonceSource(secret)` (stateless, shared by every process — and every Atlas server SDK — holding the same secret).
+- Opaque access tokens: `createAccessTokenVerifier({ introspection: { clientId, clientSecret } })` validates a token that is not a JWT at the instance's introspection endpoint (RFC 7662), caching each answer (60 seconds by default, never past `exp`; inactive answers 10 seconds). `introspectJwts: true` checks JWTs live too, so a revoked grant is refused before the token expires. DPoP-bound opaque tokens keep their sender constraint (`cnf.jkt` from introspection). `createIntrospector` is the cache on its own.
+- OAuth clients: `access_token_format` (`jwt` | `opaque`) and `token_lifetimes` (`OAuthTokenLifetimes`) on create, update and reads. Resource servers: `access_token_format`, `refresh_token_absolute_ttl_seconds`, `refresh_token_idle_ttl_seconds`, `introspection_client_ids`.
+- `RotateSigningKeyBody.key` (`main` | `secondary`) and `SigningKeyRotation.secondary_kid` for KMS setups with one key per algorithm (`config.secondary`).
+- KMS-backed signing keys: `instanceSecurity.getSigningKeyProvider()` / `setSigningKeyProvider({ provider, config, credentials })` / `removeSigningKeyProvider()` for AWS KMS, Google Cloud KMS and Azure Key Vault; `SigningKey.provider`.
+- SSO connections: SAML Single Logout fields (`saml_single_logout`, `saml_idp_slo_url`, `saml_idp_slo_response_url`, `saml_idp_slo_binding`, `saml_idp_slo_soap_url` for back-channel logout) and `saml_require_encrypted_assertions`. Reads add `has_saml_encryption_key`, `has_previous_saml_encryption_key`, `saml_encryption_rotated_at`; `SamlMetadata.slo_url`. New `getSamlEncryptionKey()`, `createSamlEncryptionKey()` (generate or rotate), `retirePreviousSamlEncryptionKey()` and `deleteSamlEncryptionKey()` (`SamlEncryptionKey`).
+- Custom OAuth 2.0 / OpenID Connect login providers: `customOAuthProviders` (`list`, `get`, `create`, `update`, `delete`, `discover`, `previewProfileMapping`, and `signingKeys(id)` with `list` / `rotate` / `retire` for `private_key_jwt`), with `ProfileMapping`, `TokenEndpointAuthMethod`, upstream (RP-initiated and front-channel) logout and third-party initiated login settings. Enterprise OIDC connections take the same `profile_mapping`, `token_endpoint_auth_method`, `client_assertion_audience`, `logout` and `idp_initiated_login`, and report `upstream_urls`.
+- Attack protection: `dormant_accounts` (`DormantAccountsSettings`), readable and writable; `country_restrictions` / `device_accounts` typed. Risk-based MFA weights and signals gain `dormantAccount`. Email template key `account_reactivated`.
+- Sessions: `custom_data` on reads and on create; `sessions.setCustomData(id, data)` (replace, `null` clears) and `sessions.updateCustomData(id, patch)` (merge).
+- Billing: add-on plans (`kind: 'base' | 'addon'`) and several subscriptions per subject (`billing.getSubscription(id)`, and `changeSubscription` / `cancelSubscription` / `restoreSubscription` by subscription id); providers `chargebee`, `autumn` and `commet` (`BillingProviderName`); plan `limits` and Autumn `seat_feature_id`; `syncPlanEntitlements(id)`; `getSettings()` / `updateSettings()` for how limits merge across subscriptions (`max` | `sum`); `checkFeature({ subject_type, subject_id, feature, required })`; metered usage takes `feature` and `subscription_id`.
+- Vercel BotID: `botIdAttestationHandler({ secret, checkBotId })` (a fetch-style route handler for your Vercel deployment) and `createBotIdAttestation()`, which sign a BotID verdict for Atlas's `vercel_botid` captcha provider.
+- `instanceSecurity.setWalletRpcSecret({ chain_id, url })`: the wallet RPC endpoint for an EIP-155 chain (token gating and the Sign in with Ethereum ENS lookup); captcha secrets take `provider`.
+
+## 0.15.0 — 2026-10-23
+
+### Added
+
+- `createAccessTokenVerifier` / `verifyAccessToken`: verify Atlas-issued OAuth access tokens in your own API or MCP server — signature against the instance JWKS, issuer, expiry, access-token type, audience (RFC 8707), required scopes (scope + permissions) and DPoP sender constraint (RFC 9449, with a replay store). Failures return the status and the RFC 6750 / RFC 9728 `WWW-Authenticate` challenge (`resource_metadata`, `insufficient_scope`).
+- `protectedResourceMetadata` / `protectedResourceMetadataPath`: build and locate your API's RFC 9728 protected-resource metadata document.
+- `buildWwwAuthenticate`, `memoryDpopReplayStore`.
+- `createTestIssuer({ alg: 'ES256' })`: an ES256 test key, like an instance switched to ES256.
+- Backend API client: `instanceSecurity.listSigningKeys()` / `rotateSigningKey({ alg, grace_period_seconds, emergency })`; `oauthClients.initialAccessTokens.list()` / `create()` / `revoke()` (RFC 7591 §3); OAuth client fields `subject_type`, `sector_identifier_uri`, `client_secret_expires_at`, `disabled`, `require_pkce` and `secret_expires_in_seconds` on create / rotate; resource server `publish_resource_metadata` and a typed `signing_alg`.
+- `users.list({ external_id })`: find a user by the id it had in the system it was migrated from.
+- User search: `users.list()` takes `query`, `email_address`, `username`, `phone_number`, `banned`, `email_verified`, `organization_id`, `created_after` / `created_before`, `order_by`, `offset` and `include_total_count` (the page then carries `total_count`).
+- Timed bans: `users.ban(id, { reason, note, expires_in_seconds, expires_at })`; `User.ban_expires_at`.
+- App roles (instance-wide, no active organization needed): `appRoles.list()` / `create()` / `get()` / `update()` / `delete()` / `listUsers()` / `getForUser()` / `setForUser()` / `removeFromUser()`; `SessionClaims.app_roles` / `app_permissions` with `hasAppRole()` / `hasAppPermission()`.
+- `createAccessControl(statements)`: typed resource/action statements for app roles — `permission()`, `permissions()`, `allPermissions()`, `role()` (a definition ready for `appRoles.create`), and `can()` / `canAny()` against session claims.
+- API key controls: create / update bodies take `enabled`, `rate_limit` (`ApiKeyRateLimit`), `remaining`, and create also `prefix` and `expires_in_seconds`; `apiKeys.verify(secret, { required_scopes })` and a coded refusal of a live key (`insufficient_scope`, `rate_limited`, `usage_exhausted`, with `missing_scopes`, `retry_after_ms`, `remaining`).
+- SCIM tokens: `scopes` and `role_mappings` on create, and `scimTokens.update()`.
+- SSO connections: `attribute_mapping` (`SsoAttributeMapping`) and `oidc_scopes`; `domain_warnings` on the connection.
+- Email template keys `email_changed`, `verification_link`, `password_reset_link`; notification `email_changed`.
+
+### Changed
+
+- Every verifier (`AtlasBackend.verify`, the OIDC relying-party helpers, `verifyLogoutToken`, `createAccessTokenVerifier`) accepts ES256 as well as RS256, since an Atlas instance — or a single API — can now sign with ES256. Verification stays pinned to those two algorithms; `none`, HMAC and anything else are refused.
+
 ## 0.14.1
 
 ### Added

package/dist/access-control.d.ts

@@ -0,0 +1,53 @@
+import type { SessionClaims } from './verify';
+/**
+ * Typed access-control definitions for app-level roles.
+ *
+ * Declare your resources and their actions once; the result gives you
+ * type-checked permission keys (`tickets:read`), role definitions you can send
+ * to `atlas.appRoles.create`, and checks against a verified session's
+ * `app_permissions` claim — so a typo in a permission is a compile error, not a
+ * silent deny.
+ *
+ * ```ts
+ * const ac = createAccessControl({
+ *   tickets: ['read', 'write', 'close'],
+ *   billing: ['read', 'refund'],
+ * } as const);
+ *
+ * const support = ac.role('support', 'Support agent', { tickets: ['read', 'write'] });
+ * await atlas.appRoles.create(support);            // { key, name, permissions: [...] }
+ *
+ * if (!ac.can(claims, { tickets: ['close'] })) return forbidden();
+ * ```
+ */
+export type AccessStatements = Readonly<Record<string, readonly string[]>>;
+/** Every `resource:action` key a statement set allows. */
+export type PermissionOf<S extends AccessStatements> = {
+    [R in keyof S & string]: `${R}:${S[R][number]}`;
+}[keyof S & string];
+/** A partial grant: some actions on some resources. */
+export type AccessGrant<S extends AccessStatements> = {
+    [R in keyof S]?: ReadonlyArray<S[R][number]>;
+};
+export interface AppRoleDefinition<S extends AccessStatements> {
+    key: string;
+    name: string;
+    description?: string;
+    permissions: Array<PermissionOf<S>>;
+}
+export interface AccessControl<S extends AccessStatements> {
+    readonly statements: S;
+    /** One typed permission key. */
+    permission<R extends keyof S & string>(resource: R, action: S[R][number]): PermissionOf<S>;
+    /** Flatten a grant into sorted permission keys. */
+    permissions(grant: AccessGrant<S>): Array<PermissionOf<S>>;
+    /** Every permission the statements define. */
+    allPermissions(): Array<PermissionOf<S>>;
+    /** An app role definition (the body `appRoles.create` takes). */
+    role(key: string, name: string, grant: AccessGrant<S>, description?: string): AppRoleDefinition<S>;
+    /** Whether the verified claims hold EVERY permission in the grant (from `app_permissions`). */
+    can(claims: SessionClaims | null | undefined, grant: AccessGrant<S>): boolean;
+    /** Whether the verified claims hold AT LEAST ONE permission in the grant. */
+    canAny(claims: SessionClaims | null | undefined, grant: AccessGrant<S>): boolean;
+}
+export declare function createAccessControl<const S extends AccessStatements>(statements: S): AccessControl<S>;

package/dist/access-control.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAccessControl = createAccessControl;
+const authz_1 = require("@atlasauth/authz");
+function createAccessControl(statements) {
+    for (const [resource, actions] of Object.entries(statements)) {
+        if (!/^[a-z][a-z0-9_]{0,63}$/.test(resource) || resource === 'org') {
+            throw new Error(`Invalid resource "${resource}": lowercase letters, digits and _, not "org".`);
+        }
+        for (const action of actions) {
+            if (!/^[a-z*][a-z0-9_*]{0,63}$/.test(action))
+                throw new Error(`Invalid action "${action}" on "${resource}".`);
+        }
+    }
+    const permissions = (grant) => {
+        const out = new Set();
+        for (const [resource, actions] of Object.entries(grant)) {
+            const allowed = statements[resource];
+            if (!allowed)
+                throw new Error(`Unknown resource "${resource}".`);
+            for (const action of actions ?? []) {
+                if (!allowed.includes(action))
+                    throw new Error(`Unknown action "${action}" on "${resource}".`);
+                out.add(`${resource}:${action}`);
+            }
+        }
+        return [...out].sort();
+    };
+    return {
+        statements,
+        permission: (resource, action) => `${resource}:${String(action)}`,
+        permissions,
+        allPermissions: () => Object.entries(statements)
+            .flatMap(([r, actions]) => actions.map((a) => `${r}:${a}`))
+            .sort(),
+        role: (key, name, grant, description) => ({
+            key,
+            name,
+            ...(description !== undefined ? { description } : {}),
+            permissions: permissions(grant),
+        }),
+        can: (claims, grant) => (0, authz_1.hasFromClaims)(claims, { allAppPermissions: permissions(grant) }),
+        canAny: (claims, grant) => (0, authz_1.hasFromClaims)(claims, { anyAppPermission: permissions(grant) }),
+    };
+}
+//# sourceMappingURL=access-control.js.map

package/dist/access-control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-control.js","sourceRoot":"","sources":["../src/access-control.ts"],"names":[],"mappings":";;AAyDA,kDAwCC;AAjGD,4CAAiD;AAyDjD,SAAgB,mBAAmB,CAAmC,UAAa;IACjF,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7D,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,gDAAgD,CAAC,CAAC;QACjG,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,SAAS,QAAQ,IAAI,CAAC,CAAC;QAChH,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,KAAqB,EAA0B,EAAE;QACpE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;QAC9B,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAuD,EAAE,CAAC;YAC9G,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;YACrC,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,QAAQ,IAAI,CAAC,CAAC;YACjE,KAAK,MAAM,MAAM,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC;gBACnC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,SAAS,QAAQ,IAAI,CAAC,CAAC;gBAC/F,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,EAA4B,CAAC;IACnD,CAAC,CAAC;IAEF,OAAO;QACL,UAAU;QACV,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,EAAqB;QACpF,WAAW;QACX,cAAc,EAAE,GAAG,EAAE,CACnB,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;aACvB,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;aAC1D,IAAI,EAA4B;QACrC,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;YACxC,GAAG;YACH,IAAI;YACJ,GAAG,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,WAAW,EAAE,WAAW,CAAC,KAAK,CAAC;SAChC,CAAC;QACF,GAAG,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,IAAA,qBAAa,EAAC,MAAM,EAAE,EAAE,iBAAiB,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACxF,MAAM,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,IAAA,qBAAa,EAAC,MAAM,EAAE,EAAE,gBAAgB,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;KAC3F,CAAC;AACJ,CAAC"}

package/dist/algs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The JWS algorithms Atlas signs tokens with. An instance key is RS256 (the
+ * default) or ES256; APIs may be set to either. Verification is pinned to this
+ * list — `none` and HMAC never verify — and the token's `kid` selects exactly
+ * one published key, whose type fixes which of the two applies.
+ */
+export declare const ATLAS_SIGNING_ALGS: string[];

package/dist/algs.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ATLAS_SIGNING_ALGS = void 0;
+/**
+ * The JWS algorithms Atlas signs tokens with. An instance key is RS256 (the
+ * default) or ES256; APIs may be set to either. Verification is pinned to this
+ * list — `none` and HMAC never verify — and the token's `kid` selects exactly
+ * one published key, whose type fixes which of the two applies.
+ */
+exports.ATLAS_SIGNING_ALGS = ['RS256', 'ES256'];
+//# sourceMappingURL=algs.js.map

package/dist/algs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"algs.js","sourceRoot":"","sources":["../src/algs.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC"}

package/dist/botid.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Vercel BotID for Atlas — the server half that runs on YOUR Vercel deployment.
+ *
+ * BotID's verdict only exists inside a Vercel-hosted request (`checkBotId()`
+ * from `botid/server` reads signals Vercel's edge attaches). Atlas is not that
+ * request, so your route runs `checkBotId()` and turns the verdict into a short
+ * signed attestation; the browser sends it to Atlas as `captcha_token`, and
+ * Atlas checks the signature, freshness and `isBot === false`, and spends it
+ * (each attestation passes once).
+ *
+ *   // app/api/atlas/botid/route.ts (Next.js on Vercel)
+ *   import { checkBotId } from 'botid/server';
+ *   import { botIdAttestationHandler } from '@atlasauth/backend';
+ *   export const POST = botIdAttestationHandler({
+ *     secret: process.env.ATLAS_BOTID_SECRET!,
+ *     checkBotId,
+ *   });
+ *
+ * The same secret is stored in Atlas for the `vercel_botid` captcha provider.
+ * Protect the route with BotID on the client (`initBotId({ protect: [{ path:
+ * '/api/atlas/botid', method: 'POST' }] })`) and set the captcha's
+ * `attestationUrl` to it, so the prebuilt components fetch a verdict on submit.
+ *
+ * Format (version 1): `atlas_botid.v1.<payload>.<sig>` — `payload` is base64url
+ * JSON `{ v: 1, is_bot, verified_bot, iat, exp, jti }`, `sig` is base64url
+ * HMAC-SHA256 over `atlas_botid.v1.<payload>` keyed by the shared secret.
+ */
+/** The prefix every attestation carries. */
+export declare const BOTID_ATTESTATION_PREFIX = "atlas_botid.v1.";
+/** Atlas refuses attestations that live longer than this, in seconds. */
+export declare const BOTID_ATTESTATION_MAX_TTL_SECONDS = 300;
+/** Atlas refuses secrets shorter than this. */
+export declare const BOTID_SECRET_MIN_LENGTH = 32;
+/** The fields of BotID's `checkBotId()` result this helper reads. */
+export interface BotIdVerdict {
+    isBot: boolean;
+    /** True for a known good bot (a search engine crawler). Recorded, still refused. */
+    isVerifiedBot?: boolean;
+}
+export interface CreateBotIdAttestationOptions {
+    /** The attestation secret shared with Atlas (at least 32 characters). */
+    secret: string;
+    /** The verdict `checkBotId()` returned for this request. */
+    verdict: BotIdVerdict;
+    /** Lifetime in seconds. Default 60, at most 300. */
+    ttlSeconds?: number;
+    /** Clock override, epoch ms (tests). */
+    now?: number;
+}
+/**
+ * Sign a BotID verdict for Atlas. Throws when the secret is too short (Atlas
+ * would refuse every attestation it signs). A bot verdict is still signed — it
+ * is Atlas that refuses it — so your route needs no branching.
+ */
+export declare function createBotIdAttestation(options: CreateBotIdAttestationOptions): string;
+export interface BotIdAttestationHandlerOptions {
+    /** The attestation secret shared with Atlas. */
+    secret: string;
+    /** `checkBotId` from `botid/server`. */
+    checkBotId: () => Promise<BotIdVerdict>;
+    /** Lifetime of each attestation in seconds. Default 60. */
+    ttlSeconds?: number;
+}
+/**
+ * A Web-standard `(request) => Response` route handler (Next.js App Router,
+ * Hono, any fetch-style runtime): runs `checkBotId()` and answers
+ * `{ token }` with the signed attestation, `no-store`. A BotID failure answers
+ * 503 so the client never sends a token that was never checked.
+ */
+export declare function botIdAttestationHandler(options: BotIdAttestationHandlerOptions): (request?: Request) => Promise<Response>;

package/dist/botid.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOTID_SECRET_MIN_LENGTH = exports.BOTID_ATTESTATION_MAX_TTL_SECONDS = exports.BOTID_ATTESTATION_PREFIX = void 0;
+exports.createBotIdAttestation = createBotIdAttestation;
+exports.botIdAttestationHandler = botIdAttestationHandler;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Vercel BotID for Atlas — the server half that runs on YOUR Vercel deployment.
+ *
+ * BotID's verdict only exists inside a Vercel-hosted request (`checkBotId()`
+ * from `botid/server` reads signals Vercel's edge attaches). Atlas is not that
+ * request, so your route runs `checkBotId()` and turns the verdict into a short
+ * signed attestation; the browser sends it to Atlas as `captcha_token`, and
+ * Atlas checks the signature, freshness and `isBot === false`, and spends it
+ * (each attestation passes once).
+ *
+ *   // app/api/atlas/botid/route.ts (Next.js on Vercel)
+ *   import { checkBotId } from 'botid/server';
+ *   import { botIdAttestationHandler } from '@atlasauth/backend';
+ *   export const POST = botIdAttestationHandler({
+ *     secret: process.env.ATLAS_BOTID_SECRET!,
+ *     checkBotId,
+ *   });
+ *
+ * The same secret is stored in Atlas for the `vercel_botid` captcha provider.
+ * Protect the route with BotID on the client (`initBotId({ protect: [{ path:
+ * '/api/atlas/botid', method: 'POST' }] })`) and set the captcha's
+ * `attestationUrl` to it, so the prebuilt components fetch a verdict on submit.
+ *
+ * Format (version 1): `atlas_botid.v1.<payload>.<sig>` — `payload` is base64url
+ * JSON `{ v: 1, is_bot, verified_bot, iat, exp, jti }`, `sig` is base64url
+ * HMAC-SHA256 over `atlas_botid.v1.<payload>` keyed by the shared secret.
+ */
+/** The prefix every attestation carries. */
+exports.BOTID_ATTESTATION_PREFIX = 'atlas_botid.v1.';
+/** Atlas refuses attestations that live longer than this, in seconds. */
+exports.BOTID_ATTESTATION_MAX_TTL_SECONDS = 300;
+/** Atlas refuses secrets shorter than this. */
+exports.BOTID_SECRET_MIN_LENGTH = 32;
+/**
+ * Sign a BotID verdict for Atlas. Throws when the secret is too short (Atlas
+ * would refuse every attestation it signs). A bot verdict is still signed — it
+ * is Atlas that refuses it — so your route needs no branching.
+ */
+function createBotIdAttestation(options) {
+    const { secret, verdict } = options;
+    if (typeof secret !== 'string' || secret.length < exports.BOTID_SECRET_MIN_LENGTH) {
+        throw new Error(`The BotID attestation secret must be at least ${exports.BOTID_SECRET_MIN_LENGTH} characters.`);
+    }
+    const ttl = Math.min(Math.max(Math.floor(options.ttlSeconds ?? 60), 1), exports.BOTID_ATTESTATION_MAX_TTL_SECONDS);
+    const iat = Math.floor((options.now ?? Date.now()) / 1000);
+    const payload = Buffer.from(JSON.stringify({
+        v: 1,
+        is_bot: verdict.isBot !== false,
+        verified_bot: verdict.isVerifiedBot === true,
+        iat,
+        exp: iat + ttl,
+        jti: (0, node_crypto_1.randomBytes)(18).toString('base64url'),
+    }), 'utf8').toString('base64url');
+    const sig = (0, node_crypto_1.createHmac)('sha256', secret).update(exports.BOTID_ATTESTATION_PREFIX + payload).digest('base64url');
+    return `${exports.BOTID_ATTESTATION_PREFIX}${payload}.${sig}`;
+}
+/**
+ * A Web-standard `(request) => Response` route handler (Next.js App Router,
+ * Hono, any fetch-style runtime): runs `checkBotId()` and answers
+ * `{ token }` with the signed attestation, `no-store`. A BotID failure answers
+ * 503 so the client never sends a token that was never checked.
+ */
+function botIdAttestationHandler(options) {
+    return async () => {
+        let verdict;
+        try {
+            verdict = await options.checkBotId();
+        }
+        catch {
+            return new Response(JSON.stringify({ error: 'botid_unavailable' }), {
+                status: 503,
+                headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+            });
+        }
+        const token = createBotIdAttestation({ secret: options.secret, verdict, ttlSeconds: options.ttlSeconds });
+        return new Response(JSON.stringify({ token }), {
+            status: 200,
+            headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+        });
+    };
+}
+//# sourceMappingURL=botid.js.map

package/dist/botid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"botid.js","sourceRoot":"","sources":["../src/botid.ts"],"names":[],"mappings":";;;AA8DA,wDAoBC;AAiBD,0DAiBC;AApHD,6CAAsD;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,4CAA4C;AAC/B,QAAA,wBAAwB,GAAG,iBAAiB,CAAC;AAE1D,yEAAyE;AAC5D,QAAA,iCAAiC,GAAG,GAAG,CAAC;AAErD,+CAA+C;AAClC,QAAA,uBAAuB,GAAG,EAAE,CAAC;AAoB1C;;;;GAIG;AACH,SAAgB,sBAAsB,CAAC,OAAsC;IAC3E,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACpC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,GAAG,+BAAuB,EAAE,CAAC;QAC1E,MAAM,IAAI,KAAK,CAAC,iDAAiD,+BAAuB,cAAc,CAAC,CAAC;IAC1G,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,yCAAiC,CAAC,CAAC;IAC3G,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC3D,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CACzB,IAAI,CAAC,SAAS,CAAC;QACb,CAAC,EAAE,CAAC;QACJ,MAAM,EAAE,OAAO,CAAC,KAAK,KAAK,KAAK;QAC/B,YAAY,EAAE,OAAO,CAAC,aAAa,KAAK,IAAI;QAC5C,GAAG;QACH,GAAG,EAAE,GAAG,GAAG,GAAG;QACd,GAAG,EAAE,IAAA,yBAAW,EAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;KAC3C,CAAC,EACF,MAAM,CACP,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACxB,MAAM,GAAG,GAAG,IAAA,wBAAU,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,gCAAwB,GAAG,OAAO,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACxG,OAAO,GAAG,gCAAwB,GAAG,OAAO,IAAI,GAAG,EAAE,CAAC;AACxD,CAAC;AAWD;;;;;GAKG;AACH,SAAgB,uBAAuB,CAAC,OAAuC;IAC7E,OAAO,KAAK,IAAI,EAAE;QAChB,IAAI,OAAqB,CAAC;QAC1B,IAAI,CAAC;YACH,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,EAAE;gBAClE,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,UAAU,EAAE;aAC7E,CAAC,CAAC;QACL,CAAC;QACD,MAAM,KAAK,GAAG,sBAAsB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;QAC1G,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;YAC7C,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,UAAU,EAAE;SAC7E,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/client/action-gallery.d.ts

@@ -0,0 +1,215 @@
+import { type RequestFn } from './request';
+import type { Action, ActionTrigger } from './actions';
+import type { ListPage } from './types';
+/**
+ * §actions gallery — browse reusable Action templates (first-party and
+ * community), install one into the instance as a DISABLED action, keep installed
+ * actions up to date, and publish your own templates for review.
+ */
+/** Every trigger a template can target (a superset of the classic three). */
+export type GalleryTrigger = ActionTrigger | 'pre_organization_create' | 'pre_member_add' | 'pre_invitation_create';
+/** A secret a template reads, declared by NAME; values are never part of a template. */
+export interface ActionTemplateSecret {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface ActionGalleryEntry {
+    object: 'action_template';
+    source: 'builtin' | 'community';
+    slug: string;
+    name: string;
+    summary: string;
+    trigger: GalleryTrigger;
+    category: string;
+    tags: string[];
+    /** SPDX licence id. */
+    license: string;
+    author: {
+        name: string;
+        first_party: boolean;
+    };
+    verified: boolean;
+    featured: boolean;
+    install_count: number;
+    latest_version: string;
+    /** The code sends outbound requests with `api.http`. */
+    uses_http: boolean;
+    secrets: ActionTemplateSecret[];
+    updated_at: number | null;
+}
+export interface ActionGalleryDetail extends ActionGalleryEntry {
+    /** Markdown. */
+    description: string;
+    code: string;
+    changelog: string | null;
+    repository_url: string | null;
+    versions: Array<{
+        version: string;
+        changelog: string | null;
+        released_at: number | null;
+    }>;
+}
+export interface ActionGalleryFilter {
+    q?: string;
+    category?: string;
+    trigger?: GalleryTrigger;
+    source?: 'builtin' | 'community';
+}
+export interface InstallTemplateBody {
+    /** A specific approved version (default: the latest). */
+    version?: string;
+    /** The action's name (default: the template's). */
+    name?: string;
+    /** Values for the secrets the template declares. Write-only. */
+    secrets?: Record<string, string>;
+}
+export interface ActionGalleryInstallResult {
+    object: 'action_gallery_install';
+    /** The new action: disabled and not bound to any flow yet. */
+    action: Action;
+    template: {
+        slug: string;
+        source: 'builtin' | 'community';
+        version: string;
+    };
+    install_id: string;
+    /** Required secrets you have not supplied yet. */
+    missing_secrets: string[];
+}
+export interface ActionGalleryInstallation {
+    object: 'action_gallery_installation';
+    action_id: string;
+    action_name: string;
+    enabled: boolean;
+    trigger: string;
+    source: 'builtin' | 'community';
+    template_slug: string;
+    installed_version: string;
+    latest_version: string | null;
+    update_available: boolean;
+    missing_secrets: string[];
+    update_requires_secrets: string[];
+    installed_at: number;
+    updated_at: number;
+}
+export interface ActionGalleryUpdateResult {
+    object: 'action_gallery_update';
+    /** false when the action already runs the latest version. */
+    updated: boolean;
+    action: Action;
+    from_version?: string;
+    version: string;
+}
+export type ActionTemplateStatus = 'draft' | 'in_review' | 'published' | 'unlisted' | 'rejected' | 'banned';
+export interface ActionTemplateVersion {
+    object: 'action_template_version';
+    version: string;
+    status: 'draft' | 'pending_review' | 'approved' | 'rejected';
+    trigger: GalleryTrigger;
+    secrets: ActionTemplateSecret[];
+    changelog: string | null;
+    /** Why staff rejected it, when they did. */
+    review_note: string | null;
+    code: string;
+    submitted_at: number | null;
+    reviewed_at: number | null;
+    created_at: number;
+}
+/** A template this instance publishes. */
+export interface ActionTemplate {
+    object: 'action_template';
+    id: string;
+    slug: string;
+    name: string;
+    author_name: string;
+    summary: string;
+    description: string | null;
+    category: string;
+    tags: string[];
+    trigger: GalleryTrigger;
+    license: string;
+    repository_url: string | null;
+    status: ActionTemplateStatus;
+    latest_version: string | null;
+    verified: boolean;
+    featured: boolean;
+    install_count: number;
+    view_count: number;
+    published_at: number | null;
+    created_at: number;
+    updated_at: number;
+    versions: ActionTemplateVersion[];
+}
+export interface ActionTemplateListing {
+    slug?: string;
+    name?: string;
+    /** Shown as the author on the gallery. */
+    author_name?: string;
+    summary?: string;
+    /** Markdown. */
+    description?: string;
+    category?: string;
+    tags?: string[];
+    trigger?: GalleryTrigger;
+    /** SPDX id (MIT, Apache-2.0, BSD-3-Clause, ISC, MPL-2.0, …). */
+    license?: string;
+    repository_url?: string | null;
+}
+export interface NewTemplateVersion {
+    /** MAJOR.MINOR.PATCH, higher than every existing version. */
+    version: string;
+    code: string;
+    secrets?: ActionTemplateSecret[];
+    changelog?: string;
+    /** Send to review right away. */
+    submit?: boolean;
+}
+export interface CreateActionTemplateBody extends ActionTemplateListing {
+    slug: string;
+    name: string;
+    author_name: string;
+    trigger: GalleryTrigger;
+    /** Optionally the first version in the same call. */
+    version?: string;
+    code?: string;
+    secrets?: ActionTemplateSecret[];
+    changelog?: string;
+    submit?: boolean;
+}
+export declare function actionGalleryResource(request: RequestFn): {
+    /** The gallery, best first. */
+    list(filter?: ActionGalleryFilter): Promise<ListPage<ActionGalleryEntry>>;
+    /** One template with its code, secret names and versions. */
+    get(slug: string): Promise<ActionGalleryDetail>;
+    /** Install as a new, disabled action. Supply secrets, bind it, then enable it. */
+    install(slug: string, body?: InstallTemplateBody, idempotencyKey?: string): Promise<ActionGalleryInstallResult>;
+    /** Actions installed from the gallery, with update status. */
+    installs(): Promise<ListPage<ActionGalleryInstallation>>;
+    /** Move an installed action to its template's latest version. */
+    update(actionId: string, body?: {
+        secrets?: Record<string, string>;
+    }): Promise<ActionGalleryUpdateResult>;
+};
+export declare function actionTemplatesResource(request: RequestFn): {
+    list(): Promise<ListPage<ActionTemplate>>;
+    create(body: CreateActionTemplateBody, idempotencyKey?: string): Promise<ActionTemplate>;
+    get(id: string): Promise<ActionTemplate>;
+    update(id: string, body: ActionTemplateListing): Promise<ActionTemplate>;
+    delete(id: string): Promise<{
+        object: "action_template";
+        id: string;
+        deleted: true;
+    }>;
+    addVersion(id: string, body: NewTemplateVersion): Promise<ActionTemplateVersion>;
+    submitVersion(id: string, version: string): Promise<ActionTemplateVersion>;
+    deleteVersion(id: string, version: string): Promise<{
+        object: "action_template_version";
+        version: string;
+        deleted: true;
+    }>;
+    /** List an approved template again after unlisting it. */
+    publish(id: string): Promise<ActionTemplate>;
+    /** Hide a template from the gallery (installs keep working). */
+    unlist(id: string): Promise<ActionTemplate>;
+};

package/dist/client/action-gallery.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.actionGalleryResource = actionGalleryResource;
+exports.actionTemplatesResource = actionTemplatesResource;
+const request_1 = require("./request");
+function actionGalleryResource(request) {
+    return {
+        /** The gallery, best first. */
+        list(filter = {}) {
+            return request({ method: 'GET', path: '/v1/action_gallery', query: { ...filter } });
+        },
+        /** One template with its code, secret names and versions. */
+        get(slug) {
+            return request({ method: 'GET', path: `/v1/action_gallery/${(0, request_1.enc)(slug)}` });
+        },
+        /** Install as a new, disabled action. Supply secrets, bind it, then enable it. */
+        install(slug, body = {}, idempotencyKey) {
+            return request({ method: 'POST', path: `/v1/action_gallery/${(0, request_1.enc)(slug)}/install`, body, idempotencyKey });
+        },
+        /** Actions installed from the gallery, with update status. */
+        installs() {
+            return request({ method: 'GET', path: '/v1/action_gallery_installs' });
+        },
+        /** Move an installed action to its template's latest version. */
+        update(actionId, body = {}) {
+            return request({ method: 'POST', path: `/v1/actions/${(0, request_1.enc)(actionId)}/gallery_update`, body });
+        },
+    };
+}
+function actionTemplatesResource(request) {
+    return {
+        list() {
+            return request({ method: 'GET', path: '/v1/action_templates' });
+        },
+        create(body, idempotencyKey) {
+            return request({ method: 'POST', path: '/v1/action_templates', body, idempotencyKey });
+        },
+        get(id) {
+            return request({ method: 'GET', path: `/v1/action_templates/${(0, request_1.enc)(id)}` });
+        },
+        update(id, body) {
+            return request({ method: 'PATCH', path: `/v1/action_templates/${(0, request_1.enc)(id)}`, body });
+        },
+        delete(id) {
+            return request({ method: 'DELETE', path: `/v1/action_templates/${(0, request_1.enc)(id)}` });
+        },
+        addVersion(id, body) {
+            return request({ method: 'POST', path: `/v1/action_templates/${(0, request_1.enc)(id)}/versions`, body });
+        },
+        submitVersion(id, version) {
+            return request({ method: 'POST', path: `/v1/action_templates/${(0, request_1.enc)(id)}/versions/${(0, request_1.enc)(version)}/submit` });
+        },
+        deleteVersion(id, version) {
+            return request({ method: 'DELETE', path: `/v1/action_templates/${(0, request_1.enc)(id)}/versions/${(0, request_1.enc)(version)}` });
+        },
+        /** List an approved template again after unlisting it. */
+        publish(id) {
+            return request({ method: 'POST', path: `/v1/action_templates/${(0, request_1.enc)(id)}/publish` });
+        },
+        /** Hide a template from the gallery (installs keep working). */
+        unlist(id) {
+            return request({ method: 'POST', path: `/v1/action_templates/${(0, request_1.enc)(id)}/unlist` });
+        },
+    };
+}
+//# sourceMappingURL=action-gallery.js.map

package/dist/client/action-gallery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-gallery.js","sourceRoot":"","sources":["../../src/client/action-gallery.ts"],"names":[],"mappings":"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"}