@vantageos/cloud-identity 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -3,9 +3,40 @@
 All notable changes to `@vantageos/cloud-identity` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.9.1]
 
-**Additive — authorize a PERSON and bind an organisation (proposed 0.8.0).**
+### Fixed
+
+- `resolveWriterRole` / `requireWriterRole`: an absent `writerRoles` list (a
+  consumer that failed to load it) now returns the typed `role-not-writer`
+  refusal instead of throwing a `TypeError`. It already granted nothing; the
+  refusal now carries its code, as the JSDoc and test promised. Found by the
+  reviewer of #15.
+
+## [0.9.0]
+
+**Additive — the person principal (`./person-principal`).** The decisions a
+server needs to serve a signed-in person in its own name, extracted from the
+first consumer so that every other one wires them the same way.
+
+### Added
+
+- `resolvePersonPrincipal`: a presented token's record -> `{ subject, orgSlug,
+  orgRole?, actor }`, or a typed refusal (not live, not a person's, no
+  organisation, organisation inactive or unmapped). Only the token's own
+  organisation is ever looked up.
+- `resolvePersonActingName` / `checkPersonCallShape`: the own-name rule. The
+  acting identity comes from the principal; another user's name and an agent's
+  name without that agent's credential are refused.
+- `resolvePersonTenantAccess`: strict organisation equality; unstamped refused.
+- `resolveWriterRole` / `requireWriterRole`: writer-role assertion, fail closed.
+- `PERSON_ACTOR_PREFIX`, `personActorName`, `isPersonActorName`,
+  `personTokenRecordSchema`, `PersonRefusalError` and the refusal types.
+- New subpath export `./person-principal`.
+
+## [0.8.0]
+
+**Additive — authorize a PERSON and bind an organisation (0.8.0).**
 A connector's `/authorize` that auto-approves with no user authentication, and
 derives the code's user from a client-registration profile, makes every client
 an anonymous app. This release is the flow that replaces it: Clerk session,

package/README.md

@@ -186,6 +186,15 @@ Visibility is granted two ways: the row's `createdBy` appears in the caller's
 `namespaceReadPrefixes`. Prefixes match on a path boundary, so a caller allowed
 `team/finance` does not thereby see `team/finance-archive`.
 
+A third way is opt-in per call. All three functions take an optional last
+argument, `grantFields` (type `GrantFieldDeclaration`, a list of property
+names). It names the row properties that carry per-row grants, such as a
+mission's `agents`. A row is then also visible when one of those properties
+names an identity in the caller's `fromAllowList`. The property can hold a
+single string or an array of strings; a value of any other shape is skipped,
+not matched. The list is data supplied by your call site; the package
+hardcodes no field names. Omitting it, or passing `[]`, adds nothing.
+
 **Token validation**
 
 - `validateMasterBearer(header, secret)` — compares an `Authorization: Bearer`
@@ -213,6 +222,8 @@ want to catch by type, and `BearerPayload`, the type returned by
 - `ValidateMasterBearerResult` — the return type of `validateMasterBearer`.
 - `ScopeFilterable` — the minimal row shape (`{ createdBy?, namespace? }`)
   accepted by `passesScopeFilter` / `scopeFilterList` / `scopeFilterGet`.
+- `GrantFieldDeclaration` — `readonly string[]`, the optional `grantFields`
+  argument of those three functions.
 - `SessionIdentity` — the human-path shape `requireTenantId` accepts under
   `{ kind: "session", identity }` (see "Both caller paths, one contract").
 - `TenantSource` — the discriminated union `requireTenantId` accepts:
@@ -370,6 +381,75 @@ Limits, stated: `redirect_uri` matching is exact (no loopback port variation);
 the package signs no access token and no id token and issues no refresh token (the consumer mints the token
 from the claims); it fetches no key set and calls no Clerk API itself.
 
+## Wiring person sign-in in an MCP server
+
+A person signed in through an OAuth connector reaches your MCP server holding a
+bearer you minted for them (see "Authorize a person and bind an organisation").
+`@vantageos/cloud-identity/person-principal` turns that bearer's token record
+into the person's principal and answers the three questions every write needs.
+It is pure: you do the lookups, it decides. A server that serves people (a PDF
+inspector, a registry, a CRM) wires it the same way:
+
+```ts
+import {
+  resolvePersonPrincipal,
+  resolvePersonActingName,
+  resolvePersonTenantAccess,
+  resolveWriterRole,
+  type PersonPrincipal,
+  type PersonRefusal,
+} from "@vantageos/cloud-identity/person-principal";
+
+// 1. Who is calling: the token row you looked up by the bearer's digest.
+const who = await resolvePersonPrincipal(
+  { principal: row.principal, subject: row.userId, orgSlug: row.orgSlug,
+    orgRole: row.orgRole, revokedAt: row.revokedAt, expiresAt: row.expiresAt },
+  { now: Date.now(), lookupOrganisation: (slug) => orgTable.get(slug) },
+  "my-tool",
+);
+if (!who.ok) return deny(who.refusal);
+
+// 2. Under what name: the token's, never the argument's.
+const name = resolvePersonActingName({
+  principal: who.principal, claimedName: args.createdBy,
+  agentCredential: presentedAgent, door: "my-tool",
+});
+if (!name.ok) return deny(name.refusal);
+
+// 3. Which rows, and may they write.
+const inOrg = resolvePersonTenantAccess({
+  principal: who.principal, rowOrgId: record.orgId, door: "my-tool" });
+const mayWrite = resolveWriterRole({
+  role: who.principal.orgRole, writerRoles: writerRolesOfOrg, door: "my-tool",
+  orgSlug: who.principal.orgSlug });
+```
+
+- `resolvePersonPrincipal(token, deps, door)` refuses a token that is expired,
+  revoked, not a person's, bound to no organisation, or bound to an inactive or
+  unmapped one. It looks up only the token's own organisation.
+- `resolvePersonActingName` returns `{ ok: true, actingAs: "person", actor }`
+  for no name or the person's own (`user:<subject>`), and refuses another
+  user's name (`PERSON_ACTS_AS_ITSELF`) and an agent's name without that
+  agent's own credential (`AGENT_CREDENTIAL_REQUIRED`, or
+  `AGENT_IDENTITY_MISMATCH` when the credential belongs to another agent).
+  `checkPersonCallShape` is the same rule for a backend door that receives a
+  person's call already stripped of its name. `PERSON_ACTOR_PREFIX`,
+  `personActorName` and `isPersonActorName` spell and reserve the actor name:
+  refuse it when someone registers an agent.
+- `resolvePersonTenantAccess` is a strict equality on the organisation; an
+  unstamped row is refused.
+- `resolveWriterRole` / `requireWriterRole` check the verified role against a
+  writer allowlist you hold as data. A missing role, a missing list and an
+  empty list all refuse. `requireWriterRole` throws `PersonRefusalError`.
+- Every refusal is a `PersonRefusal` (`PersonRefusalCode`, `PersonRefusalReason`,
+  `door`, `detail`); you choose the transport shape. `personTokenRecordSchema`,
+  `PersonTokenRecord`, `PersonPrincipal`, `OrganisationState`,
+  `PersonPrincipalDeps`, `PersonPrincipalResult`, `PersonActingNameResult` and
+  `PersonAccessResult` are the input and result types.
+
+The module verifies no credential. The token record must come from your own
+lookup of the bearer the person presented, never from a request body.
+
 ## What this package does not do
 
 Worth reading before you rely on it.

package/dist/index.d.ts

@@ -27,4 +27,6 @@ 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;AAI/B,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAChE,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,YAAY,EACV,QAAQ,EACR,SAAS,EACT,0BAA0B,EAC1B,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAClE,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,QAAQ,EACR,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACjF,YAAY,EACV,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -25,4 +25,8 @@ 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;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"}
+{"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/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. Absent or empty refuses all. */
+    writerRoles: readonly string[] | null | undefined;
+    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,218 @@
+/**
+ * @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;
+    const writerRoles = input.writerRoles ?? [];
+    if (role !== null && 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

package/dist/person-principal.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/cloud-identity",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Framework-agnostic identity + scope-filter primitives for VantagePeers Cloud (multi-tenant MCP).",
   "type": "module",
   "main": "./dist/index.js",
@@ -53,6 +53,10 @@
     "./oidc": {
       "types": "./dist/oidc.d.ts",
       "import": "./dist/oidc.js"
+    },
+    "./person-principal": {
+      "types": "./dist/person-principal.d.ts",
+      "import": "./dist/person-principal.js"
     }
   },
   "files": [