@vantageos/cloud-identity 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -17,4 +17,16 @@ export { humanAccountRoleSchema, normalizeVerifiedHumanSession, requireHumanRole
 export type { RequiredHumanRole, RoleRefusal, RoleRefusalReason, RoleResolution, HumanAccountRole, ClerkSessionLike, ResolvedHumanIdentity, } from "./human-path.js";
 export { validatePresentedBearer, requireAgentScopedIdentity, storedBearerRowSchema, } from "./presented-bearer.js";
 export type { StoredBearerRow, AgentPresence, ResolvedBearerIdentity, AgentScopedIdentity, ValidatePresentedBearerResult, RequireAgentScopedResult, PresentedBearerDeps, PresentedBearerInternalReason, } from "./presented-bearer.js";
+export { startAuthorize, resumeAuthorize, } from "./authorize-flow.js";
+export type { AuthorizeClient, ClerkOrgMembership, AuthorizationCodeRecord, AuthorizationCodeStore, ConsumeCodeResult, AuthorizeConfig, AuthorizeDeps, AuthorizeOutcome, OrgPickerModel, ResumeInput, } from "./authorize-flow.js";
+export { exchangeAuthorizationCode } from "./token-exchange.js";
+export type { AuthorizedTokenClaims, ExchangeInput, ExchangeDeps, ExchangeResult, } from "./token-exchange.js";
+export { verifyClerkSessionToken } from "./clerk-session.js";
+export type { ClerkJwk, ClerkJwks, ClerkSessionVerifierConfig, VerifiedClerkSession, VerifyClerkSessionResult, } from "./clerk-session.js";
+export { buildDiscoveryDocument, buildUserInfo } from "./oidc.js";
+export type { DiscoveryConfig, DiscoveryDocument, DiscoveryResult, ClerkUserLike, UserInfo, UserInfoResult, } from "./oidc.js";
+export { oauthErrorFor, pkceChallengeFromVerifier } from "./authorize-shared.js";
+export type { AuthorizeRefusal, AuthorizeRefusalReason, } from "./authorize-shared.js";
+export { PERSON_ACTOR_PREFIX, PersonRefusalError, personActorName, isPersonActorName, personTokenRecordSchema, resolvePersonPrincipal, resolvePersonActingName, checkPersonCallShape, resolvePersonTenantAccess, resolveWriterRole, requireWriterRole, } from "./person-principal.js";
+export type { PersonRefusal, PersonRefusalCode, PersonRefusalReason, PersonTokenRecord, PersonPrincipal, OrganisationState, PersonPrincipalDeps, PersonPrincipalResult, PersonActingNameResult, PersonAccessResult, } from "./person-principal.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,SAAS,EACT,eAAe,EACf,aAAa,EACb,aAAa,EACb,qBAAqB,EACrB,aAAa,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC1E,YAAY,EACV,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EACV,eAAe,EACf,aAAa,EACb,sBAAsB,EACtB,mBAAmB,EACnB,6BAA6B,EAC7B,wBAAwB,EACxB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -18,4 +18,15 @@ export { humanAccountRoleSchema, normalizeVerifiedHumanSession, requireHumanRole
 // NON-MASTER credential. The package's single answer to "who is calling"
 // for a presented bearer; consumers must not keep a local variant.
 export { validatePresentedBearer, requireAgentScopedIdentity, storedBearerRowSchema, } from "./presented-bearer.js";
+// 0.8.0 — Authorize a PERSON: Clerk session -> verified organisation -> a code
+// bound to both; the exchange that redeems it; the OIDC documents.
+export { startAuthorize, resumeAuthorize, } from "./authorize-flow.js";
+export { exchangeAuthorizationCode } from "./token-exchange.js";
+export { verifyClerkSessionToken } from "./clerk-session.js";
+export { buildDiscoveryDocument, buildUserInfo } from "./oidc.js";
+export { oauthErrorFor, pkceChallengeFromVerifier } from "./authorize-shared.js";
+// 0.9.0 — The person principal: a verified sign-in (person + organisation) as
+// pure data, the own-name actor rule, the tenant compare and the writer-role
+// assertion. Every consumer wires a person the same way.
+export { PERSON_ACTOR_PREFIX, PersonRefusalError, personActorName, isPersonActorName, personTokenRecordSchema, resolvePersonPrincipal, resolvePersonActingName, checkPersonCallShape, resolvePersonTenantAccess, resolveWriterRole, requireWriterRole, } from "./person-principal.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAS9D,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAU7B,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAU1E,kFAAkF;AAClF,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAWzB,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,GAEpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAS9D,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAU7B,gFAAgF;AAChF,OAAO,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAU1E,kFAAkF;AAClF,OAAO,EACL,sBAAsB,EACtB,6BAA6B,EAC7B,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,iBAAiB,CAAC;AAWzB,sEAAsE;AACtE,yEAAyE;AACzE,mEAAmE;AACnE,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAY/B,+EAA+E;AAC/E,mEAAmE;AACnE,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAa7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAOhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAQ7D,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AASlE,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAMjF,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/oidc.d.ts

@@ -0,0 +1,76 @@
+import { type AuthorizeRefusal } from "./authorize-shared.js";
+import type { AuthorizedTokenClaims } from "./token-exchange.js";
+/** Inputs of the discovery document. Every endpoint is an absolute URL. */
+export interface DiscoveryConfig {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    jwksUri: string;
+    userinfoEndpoint: string;
+    registrationEndpoint?: string;
+    scopesSupported?: readonly string[];
+}
+export interface DiscoveryDocument {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    jwks_uri: string;
+    userinfo_endpoint: string;
+    registration_endpoint?: string;
+    response_types_supported: string[];
+    response_modes_supported: string[];
+    grant_types_supported: string[];
+    subject_types_supported: string[];
+    scopes_supported: string[];
+    code_challenge_methods_supported: string[];
+    claims_supported: string[];
+}
+export type DiscoveryResult = {
+    ok: true;
+    document: DiscoveryDocument;
+} | {
+    ok: false;
+    refusal: AuthorizeRefusal;
+};
+/**
+ * Builds the discovery document (OAuth authorization-server metadata with the
+ * OIDC fields this package honours). It advertises only what is implemented:
+ * the code flow, PKCE, the `authorization_code` grant, UserInfo. It does NOT
+ * advertise id_tokens, refresh tokens or client-authentication methods; the
+ * consumer may add those keys to the returned object if it implements them. The issuer must be an https URL with no query or fragment (plain
+ * http only for loopback); every endpoint must be an absolute URL.
+ */
+export declare function buildDiscoveryDocument(config: DiscoveryConfig): DiscoveryResult;
+/** The subset of a Clerk user the UserInfo helper reads. */
+export interface ClerkUserLike {
+    id: string;
+    primaryEmailAddressId?: string | null;
+    emailAddresses: readonly {
+        id: string;
+        emailAddress: string;
+        verification?: {
+            status?: string | null;
+        } | null;
+    }[];
+}
+export interface UserInfo {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+}
+export type UserInfoResult = {
+    ok: true;
+    userinfo: UserInfo;
+} | {
+    ok: false;
+    refusal: AuthorizeRefusal;
+};
+/**
+ * Builds the UserInfo response from the Clerk user and the claims of the
+ * presented token. The token must carry `openid`; the user must be the token's
+ * subject; `email` and `email_verified` appear only when the token also
+ * carries `email` AND the user has a primary address. `email_verified` is true
+ * only for a Clerk verification status of exactly `verified`.
+ */
+export declare function buildUserInfo(claims: Pick<AuthorizedTokenClaims, "sub" | "scope">, user: ClerkUserLike): UserInfoResult;
+//# sourceMappingURL=oidc.d.ts.map

package/dist/oidc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB,EAAE,MAAM,CAAC;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gCAAgC,EAAE,MAAM,EAAE,CAAC;IAC3C,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,iBAAiB,CAAA;CAAE,GACzC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAgB7C;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAgC/E;AAED,4DAA4D;AAC5D,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,cAAc,EAAE,SAAS;QACvB,EAAE,EAAE,MAAM,CAAC;QACX,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;SAAE,GAAG,IAAI,CAAC;KAClD,EAAE,CAAC;CACL;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,GAAG,OAAO,CAAC,EACpD,IAAI,EAAE,aAAa,GAClB,cAAc,CAmBhB"}

package/dist/oidc.js

@@ -0,0 +1,83 @@
+import { PKCE_METHOD, refusal, } from "./authorize-shared.js";
+function isAbsoluteUrl(value, requireHttps) {
+    try {
+        const u = new URL(value);
+        if (u.protocol === "https:")
+            return true;
+        return (!requireHttps &&
+            u.protocol === "http:" &&
+            (u.hostname === "localhost" || u.hostname === "127.0.0.1"));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Builds the discovery document (OAuth authorization-server metadata with the
+ * OIDC fields this package honours). It advertises only what is implemented:
+ * the code flow, PKCE, the `authorization_code` grant, UserInfo. It does NOT
+ * advertise id_tokens, refresh tokens or client-authentication methods; the
+ * consumer may add those keys to the returned object if it implements them. The issuer must be an https URL with no query or fragment (plain
+ * http only for loopback); every endpoint must be an absolute URL.
+ */
+export function buildDiscoveryDocument(config) {
+    const bad = { ok: false, refusal: refusal("issuer-invalid") };
+    if (!isAbsoluteUrl(config.issuer, true))
+        return bad;
+    const issuer = new URL(config.issuer);
+    if (issuer.search !== "" || issuer.hash !== "")
+        return bad;
+    const endpoints = [
+        config.authorizationEndpoint,
+        config.tokenEndpoint,
+        config.jwksUri,
+        config.userinfoEndpoint,
+        ...(config.registrationEndpoint ? [config.registrationEndpoint] : []),
+    ];
+    if (!endpoints.every((e) => isAbsoluteUrl(e, true)))
+        return bad;
+    const document = {
+        issuer: config.issuer,
+        authorization_endpoint: config.authorizationEndpoint,
+        token_endpoint: config.tokenEndpoint,
+        jwks_uri: config.jwksUri,
+        userinfo_endpoint: config.userinfoEndpoint,
+        response_types_supported: ["code"],
+        response_modes_supported: ["query"],
+        grant_types_supported: ["authorization_code"],
+        subject_types_supported: ["public"],
+        scopes_supported: [...(config.scopesSupported ?? ["openid", "email"])],
+        code_challenge_methods_supported: [PKCE_METHOD],
+        claims_supported: ["sub", "email", "email_verified"],
+    };
+    if (config.registrationEndpoint) {
+        document.registration_endpoint = config.registrationEndpoint;
+    }
+    return { ok: true, document };
+}
+/**
+ * Builds the UserInfo response from the Clerk user and the claims of the
+ * presented token. The token must carry `openid`; the user must be the token's
+ * subject; `email` and `email_verified` appear only when the token also
+ * carries `email` AND the user has a primary address. `email_verified` is true
+ * only for a Clerk verification status of exactly `verified`.
+ */
+export function buildUserInfo(claims, user) {
+    const scopes = claims.scope.split(/\s+/);
+    if (!scopes.includes("openid")) {
+        return { ok: false, refusal: refusal("openid-scope-required") };
+    }
+    if (user.id !== claims.sub) {
+        return { ok: false, refusal: refusal("subject-mismatch") };
+    }
+    const userinfo = { sub: user.id };
+    if (scopes.includes("email")) {
+        const primary = user.emailAddresses.find((a) => a.id === user.primaryEmailAddressId);
+        if (primary) {
+            userinfo.email = primary.emailAddress;
+            userinfo.email_verified = primary.verification?.status === "verified";
+        }
+    }
+    return { ok: true, userinfo };
+}
+//# sourceMappingURL=oidc.js.map

package/dist/oidc.js.map

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

package/dist/person-principal.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @vantageos/cloud-identity 0.9.0 — the person principal.
+ *
+ * A PERSON signed in through an OAuth connector (Claude, ChatGPT, any MCP
+ * client) is not an agent. This module is the single, framework-agnostic
+ * answer to four questions a consumer must not re-implement:
+ *
+ *   1. Who is the person, and in which organisation?
+ *      `resolvePersonPrincipal` — from the record of an access token that the
+ *      consumer already looked up by its digest. Never from an argument.
+ *   2. Under what name does the person act?
+ *      `resolvePersonActingName` / `checkPersonCallShape` — its OWN name,
+ *      "user:<subject>", taken from the principal. An agent name needs that
+ *      agent's own verified credential; another user's name is refused.
+ *   3. Is a row in the person's organisation?
+ *      `resolvePersonTenantAccess` — a strict equality on the organisation.
+ *   4. May the person write?
+ *      `resolveWriterRole` / `requireWriterRole` — the verified role must be on
+ *      the writer allowlist the consumer holds as data. Fail closed.
+ *
+ * Pure functions over plain inputs: no Clerk SDK, no database, no network, no
+ * master or bypass flag anywhere in the input. The consumer performs the
+ * lookups (the token row, the organisation row, the writer list) and passes the
+ * results in; this module only decides. Every refusal is a typed value carrying
+ * its own code, reason and door, so a caller can branch on content, and an
+ * absence (no organisation, no role, no list) is a refusal, never a default.
+ *
+ * @security This module verifies NOTHING about the credential itself. The
+ * token record must come from a lookup of the bearer the person presented, made
+ * by the consumer's trusted transport layer. Passing a client-supplied object
+ * makes that object the source of subject, organisation and role.
+ */
+import { z } from "zod";
+export type PersonRefusalCode = "RBAC_DENIED" | "PERSON_ACTS_AS_ITSELF" | "AGENT_CREDENTIAL_REQUIRED" | "AGENT_IDENTITY_MISMATCH";
+export type PersonRefusalReason = "person-token-not-live" | "not-a-person-token" | "person-token-no-org" | "org-not-active" | "person-acts-as-itself" | "agent-proof-on-person-path" | "agent-credential-required" | "agent-identity-mismatch" | "other-organisation" | "role-not-writer";
+/** The typed refusal. A non-empty object carrying its own code and door. */
+export type PersonRefusal = {
+    code: PersonRefusalCode;
+    reason: PersonRefusalReason;
+    /** The consumer's own name for the entry point that refused. */
+    door: string;
+    /** One sentence, safe to show to the caller. Never a credential. */
+    detail: string;
+    /** The acting name the caller typed, when the refusal is about a name. */
+    claimed?: string;
+    /** The person's own actor name, when the refusal is about a name. */
+    self?: string;
+    /** The verified role, when the refusal is about a role (null: none). */
+    role?: string | null;
+    /** The organisation the decision was taken in, when it applies. */
+    orgSlug?: string | null;
+};
+/** Thrown by the throwing forms. Carries the typed refusal untouched. */
+export declare class PersonRefusalError extends Error {
+    readonly refusal: PersonRefusal;
+    constructor(refusal: PersonRefusal);
+}
+/** How a person is recorded as "who did it": "user:<verified subject>". */
+export declare const PERSON_ACTOR_PREFIX = "user:";
+/** The actor name of a verified subject. */
+export declare function personActorName(subject: string): string;
+/**
+ * True when `name` is spelled like a person's actor name. Such a name is
+ * RESERVED: a consumer refuses it at agent registration, so a stored actor
+ * "user:..." can only have been written from a verified subject.
+ */
+export declare function isPersonActorName(name: string): boolean;
+/**
+ * The record of a presented access token, in the package's vocabulary. The
+ * consumer maps its own row onto this shape (`subject` is the verified Clerk
+ * user id, `orgSlug` the organisation the token is bound to).
+ */
+export declare const personTokenRecordSchema: z.ZodObject<{
+    principal: z.ZodOptional<z.ZodString>;
+    subject: z.ZodString;
+    orgSlug: z.ZodOptional<z.ZodString>;
+    orgRole: z.ZodOptional<z.ZodString>;
+    revokedAt: z.ZodOptional<z.ZodNumber>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type PersonTokenRecord = z.input<typeof personTokenRecordSchema>;
+/** A verified person: who, in which organisation, with which role. */
+export type PersonPrincipal = {
+    subject: string;
+    orgSlug: string;
+    /** Present only when the token carries a verified role. Never defaulted. */
+    orgRole?: string;
+    /** "user:<subject>" — the name this person acts under. */
+    actor: string;
+};
+/** The state of an organisation as the consumer's own mapping holds it. */
+export type OrganisationState = {
+    isActive: boolean;
+};
+export type PersonPrincipalDeps<O extends OrganisationState> = {
+    /** Epoch milliseconds, supplied by the caller so the decision is pure. */
+    now: number;
+    /** Resolves the organisation row for a slug; null when unmapped. */
+    lookupOrganisation: (orgSlug: string) => Promise<O | null>;
+};
+export type PersonPrincipalResult<O extends OrganisationState> = {
+    ok: true;
+    principal: PersonPrincipal;
+    organisation: O;
+} | {
+    ok: false;
+    refusal: PersonRefusal;
+};
+/**
+ * Resolves the person behind a presented token, or refuses. Checks, in order:
+ * the token is live (present, unrevoked, unexpired); it acts for a PERSON;
+ * it is bound to an organisation; that organisation exists and is active.
+ * The only organisation ever looked up is the token's own.
+ */
+export declare function resolvePersonPrincipal<O extends OrganisationState>(token: PersonTokenRecord | null | undefined, deps: PersonPrincipalDeps<O>, door: string): Promise<PersonPrincipalResult<O>>;
+export type PersonActingNameResult = {
+    ok: true;
+    actingAs: "person";
+    actor: string;
+} | {
+    ok: true;
+    actingAs: "agent";
+    actor: string;
+} | {
+    ok: false;
+    refusal: PersonRefusal;
+};
+/**
+ * Decides under which name a person acts. The acting identity comes from the
+ * principal, never from the typed name:
+ *
+ *   - no name, or the person's own name  -> acts as itself;
+ *   - another user's name                -> PERSON_ACTS_AS_ITSELF;
+ *   - an agent's name                    -> only with that agent's own verified
+ *                                           credential (`agentCredential`,
+ *                                           resolved by the consumer): none ->
+ *                                           AGENT_CREDENTIAL_REQUIRED, a
+ *                                           different agent -> AGENT_IDENTITY_MISMATCH.
+ */
+export declare function resolvePersonActingName(input: {
+    /** Only the actor name is read: the rule needs no organisation. */
+    principal: Pick<PersonPrincipal, "actor">;
+    claimedName?: string | null;
+    /** The agent the presented credential resolved to, when one was presented. */
+    agentCredential?: {
+        agentName: string;
+    } | null;
+    door: string;
+}): PersonActingNameResult;
+/**
+ * The shape of a call that reaches a backend door ON a person's behalf: it
+ * carries no acting name (the transport already stripped the person's own) and
+ * no agent proof (a person that presented an agent credential acts as that
+ * agent, on the agent path). Returns the refusal, or null when the shape is
+ * right.
+ */
+export declare function checkPersonCallShape(input: {
+    door: string;
+    actingName?: string;
+    agentProof?: boolean;
+}): PersonRefusal | null;
+export type PersonAccessResult = {
+    ok: true;
+} | {
+    ok: false;
+    refusal: PersonRefusal;
+};
+/**
+ * A row is reachable only when its organisation stamp EQUALS the person's
+ * organisation. An absent or empty stamp never equals a resolved organisation,
+ * so an unstamped row is refused.
+ */
+export declare function resolvePersonTenantAccess(input: {
+    principal: PersonPrincipal;
+    rowOrgId: string | null | undefined;
+    door: string;
+}): PersonAccessResult;
+type WriterRoleInput = {
+    /** The VERIFIED role claim of the token. Absent or null is refused. */
+    role: string | null | undefined;
+    /** The writer allowlist the consumer holds as data. Empty refuses all. */
+    writerRoles: readonly string[];
+    door: string;
+    orgSlug?: string | null;
+};
+/**
+ * Non-throwing writer-role assertion. The role must appear EXACTLY in the
+ * allowlist; no hierarchy, no inheritance. An absent role, an absent list and
+ * an empty list all refuse: a missing list never means "all roles".
+ */
+export declare function resolveWriterRole(input: WriterRoleInput): PersonAccessResult;
+/** Throwing form of {@link resolveWriterRole}; throws `PersonRefusalError`. */
+export declare function requireWriterRole(input: WriterRoleInput): void;
+export {};
+//# sourceMappingURL=person-principal.d.ts.map

package/dist/person-principal.d.ts.map

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

package/dist/person-principal.js

@@ -0,0 +1,217 @@
+/**
+ * @vantageos/cloud-identity 0.9.0 — the person principal.
+ *
+ * A PERSON signed in through an OAuth connector (Claude, ChatGPT, any MCP
+ * client) is not an agent. This module is the single, framework-agnostic
+ * answer to four questions a consumer must not re-implement:
+ *
+ *   1. Who is the person, and in which organisation?
+ *      `resolvePersonPrincipal` — from the record of an access token that the
+ *      consumer already looked up by its digest. Never from an argument.
+ *   2. Under what name does the person act?
+ *      `resolvePersonActingName` / `checkPersonCallShape` — its OWN name,
+ *      "user:<subject>", taken from the principal. An agent name needs that
+ *      agent's own verified credential; another user's name is refused.
+ *   3. Is a row in the person's organisation?
+ *      `resolvePersonTenantAccess` — a strict equality on the organisation.
+ *   4. May the person write?
+ *      `resolveWriterRole` / `requireWriterRole` — the verified role must be on
+ *      the writer allowlist the consumer holds as data. Fail closed.
+ *
+ * Pure functions over plain inputs: no Clerk SDK, no database, no network, no
+ * master or bypass flag anywhere in the input. The consumer performs the
+ * lookups (the token row, the organisation row, the writer list) and passes the
+ * results in; this module only decides. Every refusal is a typed value carrying
+ * its own code, reason and door, so a caller can branch on content, and an
+ * absence (no organisation, no role, no list) is a refusal, never a default.
+ *
+ * @security This module verifies NOTHING about the credential itself. The
+ * token record must come from a lookup of the bearer the person presented, made
+ * by the consumer's trusted transport layer. Passing a client-supplied object
+ * makes that object the source of subject, organisation and role.
+ */
+import { z } from "zod";
+/** Thrown by the throwing forms. Carries the typed refusal untouched. */
+export class PersonRefusalError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`${refusal.code}: ${refusal.detail} (${refusal.reason}, ${refusal.door})`);
+        this.name = "PersonRefusalError";
+        this.refusal = refusal;
+    }
+}
+function refuse(code, reason, door, detail, extra = {}) {
+    return { code, reason, door, detail, ...extra };
+}
+// ---------------------------------------------------------------------------
+// Actor name
+// ---------------------------------------------------------------------------
+/** How a person is recorded as "who did it": "user:<verified subject>". */
+export const PERSON_ACTOR_PREFIX = "user:";
+/** NFC, lowercase, trim: the comparison form of an acting name. */
+function normalizeName(name) {
+    return name.normalize("NFC").toLowerCase().trim();
+}
+/** The actor name of a verified subject. */
+export function personActorName(subject) {
+    return `${PERSON_ACTOR_PREFIX}${subject}`;
+}
+/**
+ * True when `name` is spelled like a person's actor name. Such a name is
+ * RESERVED: a consumer refuses it at agent registration, so a stored actor
+ * "user:..." can only have been written from a verified subject.
+ */
+export function isPersonActorName(name) {
+    return normalizeName(name).startsWith(PERSON_ACTOR_PREFIX);
+}
+// ---------------------------------------------------------------------------
+// 1. The principal
+// ---------------------------------------------------------------------------
+/**
+ * The record of a presented access token, in the package's vocabulary. The
+ * consumer maps its own row onto this shape (`subject` is the verified Clerk
+ * user id, `orgSlug` the organisation the token is bound to).
+ */
+export const personTokenRecordSchema = z.object({
+    principal: z.string().optional(),
+    subject: z.string(),
+    orgSlug: z.string().optional(),
+    orgRole: z.string().optional(),
+    revokedAt: z.number().optional(),
+    expiresAt: z.number(),
+});
+/**
+ * Resolves the person behind a presented token, or refuses. Checks, in order:
+ * the token is live (present, unrevoked, unexpired); it acts for a PERSON;
+ * it is bound to an organisation; that organisation exists and is active.
+ * The only organisation ever looked up is the token's own.
+ */
+export async function resolvePersonPrincipal(token, deps, door) {
+    const deny = (reason, detail) => ({
+        ok: false,
+        refusal: refuse("RBAC_DENIED", reason, door, detail),
+    });
+    const parsed = personTokenRecordSchema.safeParse(token);
+    if (!parsed.success ||
+        parsed.data.revokedAt !== undefined ||
+        parsed.data.expiresAt < deps.now) {
+        return deny("person-token-not-live", "verifiedPerson names no live access token");
+    }
+    const row = parsed.data;
+    if (row.principal !== "person" || row.subject === "") {
+        return deny("not-a-person-token", "verifiedPerson names a token that does not act for a person");
+    }
+    const orgSlug = row.orgSlug;
+    if (orgSlug === undefined || orgSlug === "") {
+        return deny("person-token-no-org", "the person's token is bound to no organisation");
+    }
+    const organisation = await deps.lookupOrganisation(orgSlug);
+    if (organisation === null || !organisation.isActive) {
+        return deny("org-not-active", `Org "${orgSlug}" not in client_org_mapping or inactive`);
+    }
+    return {
+        ok: true,
+        organisation,
+        principal: {
+            subject: row.subject,
+            orgSlug,
+            ...(row.orgRole !== undefined ? { orgRole: row.orgRole } : {}),
+            actor: personActorName(row.subject),
+        },
+    };
+}
+/**
+ * Decides under which name a person acts. The acting identity comes from the
+ * principal, never from the typed name:
+ *
+ *   - no name, or the person's own name  -> acts as itself;
+ *   - another user's name                -> PERSON_ACTS_AS_ITSELF;
+ *   - an agent's name                    -> only with that agent's own verified
+ *                                           credential (`agentCredential`,
+ *                                           resolved by the consumer): none ->
+ *                                           AGENT_CREDENTIAL_REQUIRED, a
+ *                                           different agent -> AGENT_IDENTITY_MISMATCH.
+ */
+export function resolvePersonActingName(input) {
+    const { principal, door } = input;
+    const claimed = input.claimedName;
+    if (claimed === undefined || claimed === null) {
+        return { ok: true, actingAs: "person", actor: principal.actor };
+    }
+    const name = normalizeName(claimed);
+    if (name === normalizeName(principal.actor)) {
+        return { ok: true, actingAs: "person", actor: principal.actor };
+    }
+    if (name.startsWith(PERSON_ACTOR_PREFIX)) {
+        return {
+            ok: false,
+            refusal: refuse("PERSON_ACTS_AS_ITSELF", "person-acts-as-itself", door, `a person acts only in its own name; this call names "${claimed}"`, { claimed, self: principal.actor }),
+        };
+    }
+    const credential = input.agentCredential;
+    if (credential === undefined || credential === null) {
+        return {
+            ok: false,
+            refusal: refuse("AGENT_CREDENTIAL_REQUIRED", "agent-credential-required", door, `this call names "${claimed}" but carried no credential of that agent`, { claimed, self: principal.actor }),
+        };
+    }
+    if (normalizeName(credential.agentName) !== name) {
+        return {
+            ok: false,
+            refusal: refuse("AGENT_IDENTITY_MISMATCH", "agent-identity-mismatch", door, `this call names "${claimed}" but the presented credential belongs to another agent`, { claimed, self: principal.actor }),
+        };
+    }
+    return { ok: true, actingAs: "agent", actor: credential.agentName };
+}
+/**
+ * The shape of a call that reaches a backend door ON a person's behalf: it
+ * carries no acting name (the transport already stripped the person's own) and
+ * no agent proof (a person that presented an agent credential acts as that
+ * agent, on the agent path). Returns the refusal, or null when the shape is
+ * right.
+ */
+export function checkPersonCallShape(input) {
+    if (input.agentProof === true) {
+        return refuse("RBAC_DENIED", "agent-proof-on-person-path", input.door, "a person's call carries no agent credential and no verified actor");
+    }
+    if (input.actingName !== undefined) {
+        return refuse("PERSON_ACTS_AS_ITSELF", "person-acts-as-itself", input.door, `a person acts only in its own name; this call also names "${input.actingName}"`, { claimed: input.actingName });
+    }
+    return null;
+}
+/**
+ * A row is reachable only when its organisation stamp EQUALS the person's
+ * organisation. An absent or empty stamp never equals a resolved organisation,
+ * so an unstamped row is refused.
+ */
+export function resolvePersonTenantAccess(input) {
+    const { principal, rowOrgId, door } = input;
+    if (typeof rowOrgId === "string" && rowOrgId !== "" && rowOrgId === principal.orgSlug) {
+        return { ok: true };
+    }
+    return {
+        ok: false,
+        refusal: refuse("RBAC_DENIED", "other-organisation", door, "the row is outside the person's organisation (tenant boundary)", { orgSlug: principal.orgSlug }),
+    };
+}
+/**
+ * Non-throwing writer-role assertion. The role must appear EXACTLY in the
+ * allowlist; no hierarchy, no inheritance. An absent role, an absent list and
+ * an empty list all refuse: a missing list never means "all roles".
+ */
+export function resolveWriterRole(input) {
+    const role = input.role ?? null;
+    if (role !== null && input.writerRoles.includes(role))
+        return { ok: true };
+    return {
+        ok: false,
+        refusal: refuse("RBAC_DENIED", "role-not-writer", input.door, "member role is not a writer role", { role, orgSlug: input.orgSlug ?? null }),
+    };
+}
+/** Throwing form of {@link resolveWriterRole}; throws `PersonRefusalError`. */
+export function requireWriterRole(input) {
+    const r = resolveWriterRole(input);
+    if (!r.ok)
+        throw new PersonRefusalError(r.refusal);
+}
+//# sourceMappingURL=person-principal.js.map