@atlasauth/backend 0.1.0

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAtlasClient = void 0;
+// §7.3 token verification — the original surface, unchanged.
+__exportStar(require("./jwks-cache"), exports);
+__exportStar(require("./verify"), exports);
+__exportStar(require("./handshake"), exports);
+// The typed management client for the secret-key Backend API.
+var client_1 = require("./client");
+Object.defineProperty(exports, "createAtlasClient", { enumerable: true, get: function () { return client_1.createAtlasClient; } });
+__exportStar(require("./client"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6DAA6D;AAC7D,+CAA6B;AAC7B,2CAAyB;AACzB,8CAA4B;AAE5B,8DAA8D;AAC9D,mCAA6C;AAApC,2GAAA,iBAAiB,OAAA;AAE1B,2CAAyB"}

package/dist/jwks-cache.d.ts

@@ -0,0 +1,62 @@
+/**
+ * §7.3: "JWKS cached in-process with kid-miss refetch (max 1/min) so key
+ * rotation needs no deploys."
+ *
+ * The rate limit on the refetch is the security property, not a politeness.
+ * Without it, an attacker sends tokens carrying random `kid` values and every
+ * one forces an outbound request to the customer's JWKS endpoint — turning any
+ * unauthenticated caller into a traffic amplifier aimed at Atlas, from inside
+ * the customer's own infrastructure. The cache's job is as much to refuse to
+ * fetch as it is to fetch.
+ *
+ * The other half of the requirement is that rotation needs no deploy. A key
+ * that rotated an hour ago must be picked up automatically, which is exactly
+ * what the kid-miss path does — but only for a kid the cache has genuinely not
+ * seen, and only once a minute.
+ */
+/** §7.3: at most one refetch per minute, however many misses arrive. */
+export declare const REFETCH_INTERVAL_MS = 60000;
+/** §7.3 serves `Cache-Control: max-age=3600`; honoured rather than ignored. */
+export declare const DEFAULT_TTL_MS = 3600000;
+export interface Jwks {
+    keys: Array<{
+        kid?: string;
+        [claim: string]: unknown;
+    }>;
+}
+export interface JwksCacheDeps {
+    url: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    ttlMs?: number;
+    refetchIntervalMs?: number;
+}
+export type FetchOutcome = 'fresh' | 'cached' | 'refetched' | 'throttled' | 'failed';
+export declare class JwksCache {
+    private readonly deps;
+    private cached;
+    private fetchedAt;
+    private lastAttemptAt;
+    /** Exposed so a caller can assert the rate limit actually bit. */
+    lastOutcome: FetchOutcome;
+    constructor(deps: JwksCacheDeps);
+    private get now();
+    private has;
+    /**
+     * The JWKS to verify against, refetching if this `kid` is unknown.
+     *
+     * Returns whatever is cached when a refetch is throttled or fails. That is
+     * deliberate: a stale JWKS still verifies every token signed by a key it
+     * contains, so degrading to "the keys I already had" keeps the overwhelming
+     * majority of requests working through a JWKS outage. Only tokens signed by a
+     * brand-new key fail, and those are a minute old at most.
+     */
+    get(kid?: string): Promise<Jwks | null>;
+    /** Test and diagnostic surface — never used for a security decision. */
+    snapshot(): {
+        keys: number;
+        fetchedAt: number;
+    };
+}
+/** Read the `kid` from a JWT header without verifying anything. */
+export declare function readKid(jwt: string): string | undefined;

package/dist/jwks-cache.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * §7.3: "JWKS cached in-process with kid-miss refetch (max 1/min) so key
+ * rotation needs no deploys."
+ *
+ * The rate limit on the refetch is the security property, not a politeness.
+ * Without it, an attacker sends tokens carrying random `kid` values and every
+ * one forces an outbound request to the customer's JWKS endpoint — turning any
+ * unauthenticated caller into a traffic amplifier aimed at Atlas, from inside
+ * the customer's own infrastructure. The cache's job is as much to refuse to
+ * fetch as it is to fetch.
+ *
+ * The other half of the requirement is that rotation needs no deploy. A key
+ * that rotated an hour ago must be picked up automatically, which is exactly
+ * what the kid-miss path does — but only for a kid the cache has genuinely not
+ * seen, and only once a minute.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JwksCache = exports.DEFAULT_TTL_MS = exports.REFETCH_INTERVAL_MS = void 0;
+exports.readKid = readKid;
+/** §7.3: at most one refetch per minute, however many misses arrive. */
+exports.REFETCH_INTERVAL_MS = 60_000;
+/** §7.3 serves `Cache-Control: max-age=3600`; honoured rather than ignored. */
+exports.DEFAULT_TTL_MS = 3_600_000;
+class JwksCache {
+    deps;
+    cached = null;
+    fetchedAt = 0;
+    lastAttemptAt = 0;
+    /** Exposed so a caller can assert the rate limit actually bit. */
+    lastOutcome = 'fresh';
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get now() {
+        return (this.deps.now ?? Date.now)();
+    }
+    has(kid) {
+        if (!this.cached)
+            return false;
+        if (!kid)
+            return this.cached.keys.length > 0;
+        return this.cached.keys.some((key) => key.kid === kid);
+    }
+    /**
+     * The JWKS to verify against, refetching if this `kid` is unknown.
+     *
+     * Returns whatever is cached when a refetch is throttled or fails. That is
+     * deliberate: a stale JWKS still verifies every token signed by a key it
+     * contains, so degrading to "the keys I already had" keeps the overwhelming
+     * majority of requests working through a JWKS outage. Only tokens signed by a
+     * brand-new key fail, and those are a minute old at most.
+     */
+    async get(kid) {
+        const now = this.now;
+        const ttl = this.deps.ttlMs ?? exports.DEFAULT_TTL_MS;
+        const interval = this.deps.refetchIntervalMs ?? exports.REFETCH_INTERVAL_MS;
+        const expired = !this.cached || now - this.fetchedAt >= ttl;
+        const kidMiss = Boolean(this.cached) && !this.has(kid);
+        if (!expired && !kidMiss) {
+            this.lastOutcome = 'cached';
+            return this.cached;
+        }
+        /**
+         * The throttle. An attacker sending random kids must not be able to make
+         * this process hammer the JWKS endpoint — so a miss inside the window is
+         * answered from cache, and the token simply fails to verify.
+         */
+        if (kidMiss && !expired && now - this.lastAttemptAt < interval) {
+            this.lastOutcome = 'throttled';
+            return this.cached;
+        }
+        this.lastAttemptAt = now;
+        try {
+            const response = await (this.deps.fetchImpl ?? fetch)(this.deps.url, {
+                headers: { accept: 'application/json' },
+            });
+            if (!response.ok)
+                throw new Error(`JWKS fetch failed (${response.status})`);
+            const body = (await response.json());
+            if (!body || !Array.isArray(body.keys))
+                throw new Error('JWKS is malformed');
+            this.cached = body;
+            this.fetchedAt = now;
+            this.lastOutcome = kidMiss ? 'refetched' : 'fresh';
+            return this.cached;
+        }
+        catch {
+            // Keep serving what we have. A JWKS outage should degrade to "new keys
+            // do not work yet", not "nobody can authenticate".
+            this.lastOutcome = 'failed';
+            return this.cached;
+        }
+    }
+    /** Test and diagnostic surface — never used for a security decision. */
+    snapshot() {
+        return { keys: this.cached?.keys.length ?? 0, fetchedAt: this.fetchedAt };
+    }
+}
+exports.JwksCache = JwksCache;
+/** Read the `kid` from a JWT header without verifying anything. */
+function readKid(jwt) {
+    const [header] = jwt.split('.');
+    if (!header)
+        return undefined;
+    try {
+        const decoded = JSON.parse(Buffer.from(header.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8'));
+        return typeof decoded.kid === 'string' ? decoded.kid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=jwks-cache.js.map

package/dist/jwks-cache.js.map

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

package/dist/verify.d.ts

@@ -0,0 +1,162 @@
+import { type ProtectCondition } from '@atlasauth/authz';
+export { type AuthzClaims, type ProtectCondition, type ProtectOutcome, type ProtectReason, evaluate, hasFromClaims, protectFromClaims, ForbiddenError, isRoleKey, isPermissionKey, } from '@atlasauth/authz';
+/**
+ * §7.3 verification by customer backends.
+ *
+ * "verifies signature, exp/nbf with 5 s clock-skew tolerance, iss, and
+ * optionally azp against an allowlist."
+ *
+ * The design constraint that matters is what this does NOT do: it never calls
+ * Atlas on the hot path. A customer's API handling ten thousand requests a
+ * second cannot make ten thousand outbound calls to verify them, and a verifier
+ * that did would make Atlas's availability the customer's availability. So the
+ * default path is local, against cached JWKS, and the revocation window is
+ * bounded instead by the 60-second token lifetime.
+ *
+ * `verifyOnline` exists for the cases where 60 seconds is too long, and is
+ * documented as the slow path so nobody reaches for it by default.
+ */
+/** §7.3: five seconds either side, matching the server's minting tolerance. */
+export declare const CLOCK_SKEW_SECONDS = 5;
+export interface SessionClaims {
+    iss: string;
+    sub: string;
+    sid: string;
+    exp: number;
+    nbf?: number;
+    iat?: number;
+    azp?: string;
+    sv?: number;
+    mfa?: boolean;
+    org_id?: string;
+    org_slug?: string;
+    org_role?: string;
+    org_permissions?: string[];
+    /** §billing entitlement — active plan slug; gate with `has({ plan })`. */
+    pla?: string;
+    /** §billing entitlement — granted feature keys; gate with `has({ feature })`. */
+    fea?: string[];
+    /**
+     * §impersonation — RFC 8693 actor claim. Present ONLY on an impersonation
+     * session (the dashboard "impersonate" action, or a redeemed actor token); its
+     * `sub` is the operator acting AS this user. Absent on an ordinary session.
+     * Informational, never an authorization input — the operator's privilege was
+     * proven when the token was minted — so read it to render the mandatory
+     * "viewing as X" banner and to tag audit entries as impersonated, not to
+     * grant access.
+     */
+    act?: {
+        sub: string;
+    };
+    /**
+     * §migration R3 — the subject's primary verified email. Present ONLY when the
+     * instance opted in (`session.includeEmailClaim`); absent otherwise. Lets an
+     * integrator provision a first-login user from the token alone, with no
+     * `GET /v1/users/:sub` round-trip. It is a snapshot at mint time, not a live
+     * lookup — treat it as identity, not as an always-current address.
+     */
+    email?: string;
+    /**
+     * §migration R3 — the subject's `external_id`, when set (e.g. a SCIM
+     * `externalId` or an id carried over from a migration). Present only alongside
+     * `email` under the same opt-in, and only when the user carries one.
+     */
+    external_id?: string;
+    [claim: string]: unknown;
+}
+/**
+ * A verified session, carrying the ergonomic authorization helpers bound to its
+ * claims — the server-side equivalent of Clerk's `auth()`. `has()` answers a
+ * condition; `protect()` asserts one, throwing `ForbiddenError` (which the app
+ * maps to 401/403). Both delegate to the shared `@atlasauth/authz` primitive, so a
+ * check reads identically here, in the React `<Protect>`, and in Next.js.
+ */
+export interface AuthorizedSession {
+    ok: true;
+    claims: SessionClaims;
+    /**
+     * The impersonator when this is an impersonation session — the RFC 8693 `act`
+     * claim (`{ sub }`), else null. The server-side parallel of Clerk's
+     * `auth().actor`: branch on it to render the mandatory "viewing as X" banner
+     * and to tag audit entries, without reaching into `claims` untyped.
+     */
+    actor: {
+        sub: string;
+    } | null;
+    /** True when the claims satisfy the condition (empty condition = "signed in"). */
+    has(condition?: ProtectCondition): boolean;
+    /** Assert the condition; returns the claims on success, throws ForbiddenError otherwise. */
+    protect(condition?: ProtectCondition): SessionClaims;
+}
+export type VerifyResult = AuthorizedSession | {
+    ok: false;
+    reason: 'malformed' | 'invalid' | 'no_keys' | 'unauthorized_party';
+};
+export interface AtlasBackendOptions {
+    /** The instance's JWKS URL. */
+    jwksUrl: string;
+    /** Expected `iss`. Required — an unchecked issuer accepts any Atlas instance. */
+    issuer: string;
+    /**
+     * §7.3 optional azp allowlist. When set, a token minted for a different
+     * origin is refused, which is what stops a token issued to one of the
+     * customer's apps being replayed against another.
+     */
+    authorizedParties?: readonly string[];
+    secretKey?: string;
+    bapiBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+export declare class AtlasBackend {
+    private readonly options;
+    private readonly jwks;
+    constructor(options: AtlasBackendOptions);
+    /**
+     * Verify locally. No network call unless the `kid` is unknown, and at most
+     * one of those a minute.
+     */
+    verify(token: string): Promise<VerifyResult>;
+    /**
+     * §7.3 the documented slow path: ask Atlas whether the session is still live.
+     *
+     * Costs a round trip on every call, so it is for the handful of operations
+     * where a 60-second revocation window is genuinely unacceptable — deleting an
+     * account, moving money. Using it everywhere makes Atlas's availability the
+     * customer's availability, which is the thing local verification exists to
+     * avoid.
+     */
+    verifyOnline(token: string): Promise<VerifyResult>;
+    /**
+     * Verify whatever a request carries.
+     *
+     * §7.5: `__session` is readable by script for Authorization-header mode, so
+     * both carriers are legitimate. The header wins, because a caller that set it
+     * deliberately should not be overridden by a stale cookie.
+     */
+    authenticateRequest(request: {
+        headers: {
+            get(name: string): string | null;
+        } | Record<string, string | undefined>;
+    }): Promise<VerifyResult>;
+}
+/**
+ * §8.2 permission check, for gating a customer's own routes.
+ *
+ * Reads `org_permissions` off the token rather than calling Atlas, which is the
+ * whole point of putting them in the claims — and it means a permission change
+ * takes effect within one token lifetime, the same bound as revocation.
+ */
+export declare function hasPermission(claims: SessionClaims, permission: string): boolean;
+export declare function hasRole(claims: SessionClaims, role: string): boolean;
+/**
+ * The full-condition check for a bare claims object — the standalone twin of the
+ * bound `result.has()`, for code that already holds claims (e.g. from a JWT it
+ * decoded itself). Supports permission / role / anyPermission / allPermissions.
+ */
+export declare function has(claims: SessionClaims, condition?: ProtectCondition): boolean;
+/**
+ * Assert a condition against a bare claims object, throwing `ForbiddenError`
+ * when unmet. The standalone twin of the bound `result.protect()`.
+ */
+export declare function protect(claims: SessionClaims, condition?: ProtectCondition): SessionClaims;

package/dist/verify.js

@@ -0,0 +1,226 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlasBackend = exports.CLOCK_SKEW_SECONDS = exports.isPermissionKey = exports.isRoleKey = exports.ForbiddenError = exports.protectFromClaims = exports.hasFromClaims = exports.evaluate = void 0;
+exports.hasPermission = hasPermission;
+exports.hasRole = hasRole;
+exports.has = has;
+exports.protect = protect;
+const jose_1 = require("jose");
+const authz_1 = require("@atlasauth/authz");
+const jwks_cache_1 = require("./jwks-cache");
+// Re-export the shared authorization primitive so a backend customer imports
+// `has`, `protect`, `ProtectCondition`, etc. from `@atlasauth/backend` directly —
+// the same contract `@atlasauth/react` and `@atlasauth/nextjs` evaluate.
+var authz_2 = require("@atlasauth/authz");
+Object.defineProperty(exports, "evaluate", { enumerable: true, get: function () { return authz_2.evaluate; } });
+Object.defineProperty(exports, "hasFromClaims", { enumerable: true, get: function () { return authz_2.hasFromClaims; } });
+Object.defineProperty(exports, "protectFromClaims", { enumerable: true, get: function () { return authz_2.protectFromClaims; } });
+Object.defineProperty(exports, "ForbiddenError", { enumerable: true, get: function () { return authz_2.ForbiddenError; } });
+Object.defineProperty(exports, "isRoleKey", { enumerable: true, get: function () { return authz_2.isRoleKey; } });
+Object.defineProperty(exports, "isPermissionKey", { enumerable: true, get: function () { return authz_2.isPermissionKey; } });
+/**
+ * §7.3 verification by customer backends.
+ *
+ * "verifies signature, exp/nbf with 5 s clock-skew tolerance, iss, and
+ * optionally azp against an allowlist."
+ *
+ * The design constraint that matters is what this does NOT do: it never calls
+ * Atlas on the hot path. A customer's API handling ten thousand requests a
+ * second cannot make ten thousand outbound calls to verify them, and a verifier
+ * that did would make Atlas's availability the customer's availability. So the
+ * default path is local, against cached JWKS, and the revocation window is
+ * bounded instead by the 60-second token lifetime.
+ *
+ * `verifyOnline` exists for the cases where 60 seconds is too long, and is
+ * documented as the slow path so nobody reaches for it by default.
+ */
+/** §7.3: five seconds either side, matching the server's minting tolerance. */
+exports.CLOCK_SKEW_SECONDS = 5;
+/** Build the success result with `has`/`protect` bound to the verified claims. */
+function authorized(claims) {
+    return {
+        ok: true,
+        claims,
+        // Normalize to a typed `{ sub }` or null — never leak a malformed `act`
+        // (e.g. `act` present but `sub` missing) through as a truthy actor.
+        actor: claims.act && typeof claims.act.sub === 'string' && claims.act.sub
+            ? { sub: claims.act.sub }
+            : null,
+        has: (condition = {}) => (0, authz_1.hasFromClaims)(claims, condition),
+        protect: (condition = {}) => {
+            const outcome = (0, authz_1.evaluate)(claims, condition);
+            if (!outcome.allowed)
+                throw new authz_1.ForbiddenError(outcome.reason, condition);
+            return claims;
+        },
+    };
+}
+class AtlasBackend {
+    options;
+    jwks;
+    constructor(options) {
+        this.options = options;
+        this.jwks = new jwks_cache_1.JwksCache({
+            url: options.jwksUrl,
+            fetchImpl: options.fetchImpl,
+            now: options.now,
+        });
+    }
+    /**
+     * Verify locally. No network call unless the `kid` is unknown, and at most
+     * one of those a minute.
+     */
+    async verify(token) {
+        if (!token || token.split('.').length !== 3)
+            return { ok: false, reason: 'malformed' };
+        const keys = await this.jwks.get((0, jwks_cache_1.readKid)(token));
+        if (!keys || keys.keys.length === 0)
+            return { ok: false, reason: 'no_keys' };
+        let claims;
+        try {
+            const { payload } = await (0, jose_1.jwtVerify)(token, (0, jose_1.createLocalJWKSet)(keys), {
+                // Pinned. Without this, a token whose header says `alg: none` — or any
+                // algorithm the key material can be coerced into — verifies.
+                algorithms: ['RS256'],
+                issuer: this.options.issuer,
+                clockTolerance: exports.CLOCK_SKEW_SECONDS,
+                currentDate: this.options.now ? new Date(this.options.now()) : undefined,
+            });
+            claims = payload;
+        }
+        catch {
+            /**
+             * One reason for every failure. Telling a caller whether the signature,
+             * the issuer or the expiry was wrong helps someone refining a forged
+             * token far more than it helps a developer debug a real one.
+             */
+            return { ok: false, reason: 'invalid' };
+        }
+        /**
+         * §13.1 token-confusion guard. An OP access token (`token_use:'access_token'`)
+         * and an id_token (carries `aud`) are signed with the SAME per-instance RS256
+         * key, issuer and `typ:'JWT'` header as a first-party session JWT. Reject any
+         * token carrying an OP marker so a "Sign in with Atlas" RP cannot replay one
+         * as a customer session. An ABSENT `token_use`/`aud` is a valid session
+         * (backward-compat for tokens minted before the `token_use:'session'` marker),
+         * so this never mass-invalidates a live fleet.
+         */
+        const tokenUse = claims.token_use;
+        if ((tokenUse !== undefined && tokenUse !== 'session') || claims.aud !== undefined) {
+            return { ok: false, reason: 'invalid' };
+        }
+        if (this.options.authorizedParties?.length) {
+            if (!claims.azp || !this.options.authorizedParties.includes(claims.azp)) {
+                return { ok: false, reason: 'unauthorized_party' };
+            }
+        }
+        // The single success-construction point — verifyOnline and
+        // authenticateRequest both return this result, so the bound has()/protect()
+        // ride along every verification path.
+        return authorized(claims);
+    }
+    /**
+     * §7.3 the documented slow path: ask Atlas whether the session is still live.
+     *
+     * Costs a round trip on every call, so it is for the handful of operations
+     * where a 60-second revocation window is genuinely unacceptable — deleting an
+     * account, moving money. Using it everywhere makes Atlas's availability the
+     * customer's availability, which is the thing local verification exists to
+     * avoid.
+     */
+    async verifyOnline(token) {
+        const local = await this.verify(token);
+        if (!local.ok)
+            return local;
+        if (!this.options.secretKey || !this.options.bapiBaseUrl) {
+            throw new Error('verifyOnline needs secretKey and bapiBaseUrl. Without them it would silently fall back to local verification, which is the opposite of what the caller asked for.');
+        }
+        try {
+            const response = await (this.options.fetchImpl ?? fetch)(`${this.options.bapiBaseUrl}/v1/tokens/verify`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Bearer ${this.options.secretKey}`,
+                    'content-type': 'application/json',
+                },
+                body: JSON.stringify({ token }),
+            });
+            if (!response.ok)
+                return { ok: false, reason: 'invalid' };
+            const body = (await response.json());
+            return body.verified ? local : { ok: false, reason: 'invalid' };
+        }
+        catch {
+            /**
+             * Fails CLOSED. The caller reached for verifyOnline precisely because a
+             * stale answer was unacceptable, so returning the local result on an
+             * outage would give them the thing they explicitly refused.
+             */
+            return { ok: false, reason: 'invalid' };
+        }
+    }
+    /**
+     * Verify whatever a request carries.
+     *
+     * §7.5: `__session` is readable by script for Authorization-header mode, so
+     * both carriers are legitimate. The header wins, because a caller that set it
+     * deliberately should not be overridden by a stale cookie.
+     */
+    async authenticateRequest(request) {
+        const header = readHeader(request.headers, 'authorization');
+        const cookie = readHeader(request.headers, 'cookie');
+        const bearer = header?.startsWith('Bearer ') ? header.slice(7) : undefined;
+        const fromCookie = cookie ? readCookie(cookie, '__session') : undefined;
+        const token = bearer ?? fromCookie;
+        if (!token)
+            return { ok: false, reason: 'malformed' };
+        return this.verify(token);
+    }
+}
+exports.AtlasBackend = AtlasBackend;
+function readHeader(headers, name) {
+    if (typeof headers.get === 'function') {
+        return headers.get(name) ?? undefined;
+    }
+    const record = headers;
+    return record[name] ?? record[name.toLowerCase()];
+}
+function readCookie(header, name) {
+    for (const part of header.split(';')) {
+        const [key, ...rest] = part.trim().split('=');
+        if (key === name)
+            return rest.join('=');
+    }
+    return undefined;
+}
+/**
+ * §8.2 permission check, for gating a customer's own routes.
+ *
+ * Reads `org_permissions` off the token rather than calling Atlas, which is the
+ * whole point of putting them in the claims — and it means a permission change
+ * takes effect within one token lifetime, the same bound as revocation.
+ */
+function hasPermission(claims, permission) {
+    return (0, authz_1.hasFromClaims)(claims, { permission });
+}
+function hasRole(claims, role) {
+    return (0, authz_1.hasFromClaims)(claims, { role });
+}
+/**
+ * The full-condition check for a bare claims object — the standalone twin of the
+ * bound `result.has()`, for code that already holds claims (e.g. from a JWT it
+ * decoded itself). Supports permission / role / anyPermission / allPermissions.
+ */
+function has(claims, condition = {}) {
+    return (0, authz_1.hasFromClaims)(claims, condition);
+}
+/**
+ * Assert a condition against a bare claims object, throwing `ForbiddenError`
+ * when unmet. The standalone twin of the bound `result.protect()`.
+ */
+function protect(claims, condition = {}) {
+    const outcome = (0, authz_1.evaluate)(claims, condition);
+    if (!outcome.allowed)
+        throw new authz_1.ForbiddenError(outcome.reason, condition);
+    return claims;
+}
+//# sourceMappingURL=verify.js.map

package/dist/verify.js.map

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

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@atlasauth/backend",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "jose": "^5.9.6",
+    "@atlasauth/authz": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}