@godxjp/server-sdk 0.1.0

package/README.md

@@ -0,0 +1,486 @@
+# @godxjp/server-sdk
+
+GoDX **server-side** SDK for JS runtimes — Cloudflare Workers first, Node-compatible. It holds
+service credentials (client secrets, session keys), so it must never be bundled for the browser:
+every subpath resolves a throwing guard under the `browser` export condition, and `workerd` /
+`worker` are listed before it because Cloudflare Workers also match `browser`. For frontend code
+use `@godxjp/web-sdk`. Counterpart of [`godx-jp/php-sdk`](https://github.com/godx-jp/php-sdk) —
+the two SDKs are kept answering the same way, with mirrored test suites as the guard.
+
+Naming is by **side**, not by language (`web-sdk` / `server-sdk` / `php-sdk`) — see
+`docs/explanation/naming-conventions.md` in `godx-jp/id`.
+
+## Modules
+
+| Subpath | What it owns |
+|---|---|
+| `./auth` | The verified, immutable `Principal` (one parse gate: `verifyAccessToken`), PKCE, sealed session values (JWE). Verification failures say **expected vs actual** (`iss`/`aud`), because a bare "unexpected claim" costs whoever reads it a debugging session. The token audience is the **ServiceInstance slug**, not the service slug. |
+| `./authorization` | `fetchEffectivePermissions` — the effective-access read model (`/api/sso/me/permissions`), `authoritative` flag passed through, never cached as a positive grant. |
+| `./http` | OIDC discovery (cached per isolate; endpoints are read, never hardcoded), `GodxSsoClient` (authorize URL, code exchange, refresh, revoke, userinfo), the server-to-server service API (`X-Service-Slug`/`X-Service-Secret`). |
+| `./hono` | Thin adapter: `godxSso()` mounts `/auth/{login,callback,logout}`, `requireAuth`, `requireWritable` (read-only organizations may not write), `dockProxy` (the GoDX Dock's `apiBase` lane — no CORS, no token in the page). Every SSO failure lands back on the app as `/?sso_error=…&sso_error_description=…` with a human-readable description. |
+| `./sync` | The identity feed, both consumer legs — see below. |
+| `./org` | Typed client for the **write-back** surface (`/api/org/v1/*`): me, employees, departments, branches, teams (list / paginate-all / create). `Idempotency-Key` on every write (IETF draft), RFC 6750 `WWW-Authenticate` surfaced on 401/403, 422 field errors and 429 `Retry-After` exposed on `OrgApiError`. Tenancy is the token's — the client never sends an organization id. Since godx-jp/id#1960, a downstream **service-launch token carries the `organization-api` audience whenever org.\* scopes are granted** (i.e. survive RBAC narrowing) — see [`./org`](#org--the-write-back-client) below. |
+
+Core modules depend on `fetch` + WebCrypto only; `hono` is the only framework-shaped subpath.
+
+### Package exports — condition order is load-bearing
+
+`package.json` maps every subpath as:
+
+```json
+{ "workerd": "./src/x.ts", "worker": "./src/x.ts", "browser": "./src/browser-guard.ts", "default": "./src/x.ts" }
+```
+
+`workerd` and `worker` **must stay listed before `browser`**: Cloudflare's bundler matches the
+`browser` condition too, and with the order flipped a Worker build resolves the throwing guard
+instead of the real module. The guard (`src/browser-guard.ts`) throws at import time with a
+message pointing at `@godxjp/web-sdk`.
+
+## Quickstart (Hono on Workers)
+
+```ts
+import { godxSso, type GodxVariables } from "@godxjp/server-sdk/hono";
+
+type AppEnv = { Bindings: Env; Variables: GodxVariables };
+
+const sso = godxSso<AppEnv>((env) => ({
+  issuer: env.GODX_ISSUER,                    // e.g. https://platform.test
+  serviceSlug: env.GODX_SERVICE_SLUG,         // catalog slug: "boilerplate"
+  audience: env.GODX_AUDIENCE,                // ServiceInstance slug: "boilerplate-local"
+  clientId: env.GODX_CLIENT_ID,
+  clientSecret: env.GODX_CLIENT_SECRET,
+  redirectUri: `${env.APP_URL}/auth/callback`,
+  sessionSecret: env.SESSION_SECRET,
+  defaultOrganizationContextId: env.GODX_DEFAULT_ORG_CONTEXT || undefined,
+}));
+
+app.route("/auth", sso.routes);
+app.all("/api/dock/v1/*", sso.requireAuth, sso.dockProxy);
+app.use("/api/*", sso.requireAuth, sso.requireWritable);
+// handlers read c.get("principal").organizationId and scope every query by it
+```
+
+The platform's launch URL carries `organization_context_id`; `/auth/login` forwards it (or falls
+back to `defaultOrganizationContextId` for local dev). A session is bound to the token's
+`organization_id` — an org switch is a new SSO round, never a reused session.
+
+### `GodxSsoConfig` — every field
+
+| Field | Required | Default | Notes |
+|---|---|---|---|
+| `issuer` | yes | — | Platform origin; OIDC discovery is read from `{issuer}/.well-known/openid-configuration`, endpoints are never hardcoded. |
+| `serviceSlug` | yes | — | Catalog **service** slug; sent as `service_slug` on authorize and token requests. |
+| `clientId` | yes | — | ServiceInstance OAuth client id (`si_…`). |
+| `clientSecret` | no | `undefined` | Omit for a public (secretless) instance — PKCE alone then. |
+| `redirectUri` | yes | — | Must match the instance's `allowed_redirect_uris` exactly (scheme, host, port, path). |
+| `sessionSecret` | yes | — | Hashed (SHA-256) into the JWE key that seals the `gx_txn` and `gx_sess` cookies (dir/A256GCM). |
+| `scope` | no | `"openid profile email"` | Space-separated. Add `org.*` words to reach `/api/org/v1` — they are granted only as far as the signing-in user's RBAC reaches. |
+| `audience` | no | `serviceSlug` | Expected token `aud` = your **ServiceInstance slug** (`boilerplate-local`), *not* the service slug. Leaving it unset only works when the two happen to be equal — they usually are not. |
+| `defaultOrganizationContextId` | no | `undefined` | `console_organization_id` fallback for logins **not** started from a platform launch URL. Dev convenience only; leave unset in production multi-org setups. |
+
+`godxSso(getConfig)` returns `{ routes, requireAuth, requireWritable, dockProxy }`:
+
+| Member | Type | Behaviour |
+|---|---|---|
+| `routes` | `Hono` | `GET /login` (PKCE + state in a sealed 5-min `gx_txn` cookie, forwards `organization_context_id`), `GET /callback` (code exchange → `verifyAccessToken` → one `userinfo` call for display name → seals `{principal, accessToken}` into `gx_sess` with TTL = token exp), `GET /logout` (best-effort revoke, then redirect to `end_session_endpoint`). Every failure redirects to `/?sso_error=…&sso_error_description=…`. |
+| `requireAuth` | middleware | Opens `gx_sess`; 401 `{"error":"unauthenticated"}` when missing/expired. Sets `c.set("principal", …)` and `c.set("accessToken", …)` (the `GodxVariables` pair). |
+| `requireWritable` | middleware | Enforces `organization_access_mode`: non-GET/HEAD/OPTIONS from a `read_only` org answers 403. |
+| `dockProxy` | middleware | Forwards `/api/dock/v1/*` to the platform with the session's Bearer token — the GoDX Dock `apiBase` lane: no CORS, no token in the page. Mount it behind `requireAuth` and **before** any `requireWritable` (Dock actions are the platform's to authorize). Passes `X-Request-Id` back through. |
+
+## API reference
+
+Every export per subpath, checked against `src/*.ts`.
+
+### `./auth`
+
+| Export | Signature (condensed) | One line |
+|---|---|---|
+| `Principal` | `interface { sub, organizationId, accessMode, scopes, serviceInstanceId?, clientId?, expiresAt, name?, email? }` | The verified, frozen identity; `accessMode` defaults to `read_only` unless the claim says `full` (fail closed). |
+| `verifyAccessToken` | `(token, {issuer, serviceSlug, audience?}) => Promise<Principal>` | The one parse gate: JWKS signature, exact `iss`, `aud` (= instance slug, defaults to `serviceSlug`), `exp`, then requires `organization_id`. Failures quote expected vs actual `iss`/`aud`. |
+| `Pkce` | `interface { verifier, challenge, method: "S256" }` | A PKCE pair. |
+| `createPkce` | `() => Promise<Pkce>` | S256 challenge via WebCrypto. |
+| `randomToken` | `(bytes = 16) => string` | base64url random token (state, nonce). |
+| `sealData` | `(payload, secret, ttlSeconds) => Promise<string>` | Encrypt+sign into a compact cookie value (JWE dir/A256GCM; key = SHA-256 of secret). |
+| `openData` | `<T>(token, secret) => Promise<T \| null>` | Inverse of `sealData`; returns `null` for anything invalid or expired — never throws on bad input. |
+
+### `./authorization`
+
+| Export | Signature | One line |
+|---|---|---|
+| `EffectiveAccess` | `interface { permissions, roles, serviceAccess, contractVersion?, evaluatedAt?, authoritative }` | The effective-access read model. |
+| `fetchEffectivePermissions` | `({issuer, accessToken, organizationId, branchId?}) => Promise<EffectiveAccess>` | `GET /api/sso/me/permissions`; `authoritative` passed through as-is — never cache a non-authoritative answer as a positive grant. |
+
+### `./http`
+
+| Export | Signature | One line |
+|---|---|---|
+| `IssuerMetadata` / `Issuer` | interfaces | OIDC discovery document / metadata + remote JWKS pair. |
+| `GodxHttpError` | `class extends Error { status, body }` | Every non-OK platform answer; base class of `OrgApiError`. |
+| `loadIssuer` | `(issuerUrl) => Promise<Issuer>` | Discovery + JWKS, cached per isolate; a failed load evicts itself from the cache. |
+| `SsoClientConfig` / `TokenResponse` / `UserinfoResponse` | interfaces | Client config and wire shapes. |
+| `GodxSsoClient` | `class (config)` — `authorizeUrl(params)`, `exchangeCode({code, codeVerifier})`, `refresh(refreshToken)`, `revoke(token)`, `userinfo(accessToken)` | The OAuth/OIDC client. `authorizeUrl` sends `service_slug`, PKCE S256 and optional `organization_context_id`; `revoke` is a no-op when discovery lists no revocation endpoint. |
+| `createServiceApi` | `({issuer, serviceSlug, serviceSecret}) => { users(q), branches(q), brands(q) }` | Server-to-server reads with `X-Service-Slug`/`X-Service-Secret`. Rate-limited by the platform (429) — cache and back off; no auto-retry here. |
+
+### `./hono`
+
+| Export | Signature | One line |
+|---|---|---|
+| `GodxSsoConfig` | interface | See the field table above. |
+| `GodxVariables` | `{ principal: Principal; accessToken: string }` | What `requireAuth` puts on the Hono context. |
+| `godxSso` | `<E>(getConfig: (env) => GodxSsoConfig) => { routes, requireAuth, requireWritable, dockProxy }` | The adapter factory; see the member table above. |
+
+### `./sync`
+
+| Export | Signature | One line |
+|---|---|---|
+| `IdentityFamily` | union type | `organization \| brand \| branch \| user \| employee \| service_user_access \| org_service_role \| role_assignment`. |
+| `KNOWN_CONTRACT_VERSIONS` | `["v1", "v2"]` | An unknown `contract_version` **stops** the consumer, never guesses. |
+| `IdentityEnvelope` | interface | CloudEvents 1.0 envelope as the relay publishes it (`id` = idempotency key, `sequence` = ordering fence, `subject` = `{family}/{id}`). |
+| `ParsedSubject` | `{ family, id }` | Split subject. |
+| `SyncContractError` | `class extends Error` | Every contract violation. |
+| `parseSubject` | `(subject) => ParsedSubject` | Rejects anything not exactly `{family}/{id}`. |
+| `parseEnvelope` | `(raw, {expectedSource?}?) => IdentityEnvelope` | Validates specversion/id/type/sequence/subject, optionally pins `source`; expected-vs-actual error messages. |
+| `Projector` | `interface { apply(subject, data, context) }` | One code path for snapshot rows AND stream events; `data` is a full mirrored payload, never a diff. |
+| `ProjectorContext` | `{ organizationId, sequence }` | The watermark the row is consistent up to. |
+| `Transport` | `interface { pull(handler) }` | The stream-leg seam (JetStream durable on a Node host). **Not implemented here yet.** |
+| `Inbox` | `interface { seen(eventId), record(eventId, sequence) }` | Dedupe seam keyed on the CloudEvents `id`. |
+| `TenantPolicy` / `acceptTenants` | `{ allows(source, orgId) }` / `(source, orgIds) => TenantPolicy` | Which (source, organization) pairs this consumer accepts; a refusal is a `terminated` outcome, never an exception. |
+| `Outcome` / `Delivery` | union / `{ outcome, eventId, reason? }` | What happened to one delivery — full table below. |
+| `createProcessor` | `({projector, inbox, tenantPolicy?, families?}) => (envelope) => Promise<Delivery>` | The one pipeline: validate → dedupe → tenant gate → project → record. |
+| `D1_INBOX_DDL` | `string` | DDL for the inbox table — copy into a migration verbatim (below). |
+| `createD1Inbox` | `(db, table = "godx_sync_inbox") => Inbox` | Inbox over anything with D1's `prepare/bind` surface. |
+| `signWebhook` | `(secret, body, {id?, timestamp?}?) => Promise<headers>` | Standard Webhooks signing — the bridge's half; also handy in tests. |
+| `verifyWebhook` | `(secret, body, headers) => Promise<string \| null>` | `null` when valid, else a human-readable refusal; constant-time compare, ±5 min replay tolerance, multiple space-separated signatures (key rotation), `whsec_` or raw secrets. |
+| `IngestResult` | `{ deliveries, response }` | Exported pair type for callers that want both halves. |
+| `handleIngestRequest` | `(request: Request, {secret, process, expectedSource?}) => Promise<Response>` | The whole HTTP ingest endpoint — pure fetch API, one line to mount from any framework. |
+| `SnapshotRow` / `SnapshotPage` / `ReconcileResult` | interfaces | Snapshot wire shapes and the pass summary (`sequence` watermark, pages, rows). |
+| `createSnapshotClient` | `({issuer, serviceSlug, serviceSecret}) => { fetchPage(family, {cursor?, limit?}), reconcile(family, projector, {limit?}) }` | Keyset-paged `GET /api/sso/service/snapshot/{family}` to completion; per-status hints on failure (410 → restart the pass, 403 → `service_api_enabled`, …). |
+
+### `./org`
+
+See [the dedicated section](#org--the-write-back-client) for the client surface, error handling
+and the scope→permission mapping.
+
+| Export | Signature | One line |
+|---|---|---|
+| `OrgApiConfig` | `{ issuer, accessToken }` | Bearer token whose `aud` includes `{issuer}/api/org/v1`. |
+| `PageMeta` / `Page<T>` | interfaces | Laravel-style page envelope (`data` + `meta`). |
+| `OrgEmployee` / `OrgDepartment` / `OrgBranch` / `OrgTeam` / `OrgMe` | interfaces | Row shapes (open-ended: `[key: string]: unknown`). |
+| `OrgApiError` | `class extends GodxHttpError { wwwAuthenticate, retryAfterSeconds, validationErrors }` | Every non-OK org/v1 answer, with the standard headers/bodies surfaced as fields. |
+| `createOrgApi` | `(config) => { me, employees, departments, branches, teams }` | The typed client; method table below. |
+
+## `./sync` — the identity feed
+
+The platform publishes identity/directory changes (organizations, branches, brands, users,
+employees, access grants) as CloudEvents on NATS JetStream — contract:
+`docs/reference/identity-feed-protocol.md` in `godx-jp/id` (v2). **The feed is one-way.** A
+service that wants to change platform data writes back through the platform's own APIs
+(`/api/console/*`, `/api/org/v1/*`), never by publishing to the bus; the change then comes back
+around the loop to every consumer, this one included.
+
+The loop closes through `./org`: **read** via the feed's projections, **write** via
+`/api/org/v1/*` — a service's write comes back around the feed to every consumer, itself
+included (its own projector then answers `applied` with the platform-assigned sequence, which is
+also how a service confirms its write propagated).
+
+A Worker cannot hold a JetStream durable (no long-lived process), so this module implements the
+two legs a Worker *can* run:
+
+```
+                    ┌─────────── platform (godx-jp/id) ───────────┐
+   writes via API → │ MySQL → identity_outbox → IdentityOutboxRelay│
+                    └──────┬───────────────────────────┬───────────┘
+                     NATS JetStream               WebhookTransport (PR #1956)
+                     (hosts with a durable)        CloudEvents + Standard Webhooks
+                           │                             │
+                           ▼                             ▼
+                     php-sdk Receiver          handleIngestRequest  ← YOU ARE HERE (event leg)
+                                               createSnapshotClient ← and here (reconcile leg)
+                                                        │
+                                                   Projector → your D1 mirror
+```
+
+### Reconcile leg (pull, HTTP)
+
+`createSnapshotClient(...).reconcile(family, projector)` pages
+`GET /api/sso/service/snapshot/{family}` (keyset cursor) to completion and reports the
+`sequence` watermark. It is a projection of **current state**, not a replay. Rules encoded:
+unknown `contract_version` stops instead of guessing; `410 CURSOR_EXPIRED` means restart the
+pass from the beginning; snapshot first, **then** resume events from the watermark — never the
+reverse.
+
+### Event leg (push, HTTP)
+
+A bridge — the platform's `WebhookTransport`, or any JetStream puller — POSTs each event here:
+
+```ts
+app.post("/api/sync/ingest", (c) =>
+  handleIngestRequest(c.req.raw, {
+    secret: c.env.SYNC_WEBHOOK_SECRET,          // whsec_...
+    expectedSource: c.env.GODX_ISSUER,          // pin the issuer per environment
+    process: createProcessor({
+      projector: myProjector(drizzle(c.env.DB)),
+      inbox: createD1Inbox(c.env.DB),           // table: D1_INBOX_DDL
+      families: ["organization"],
+      tenantPolicy: acceptTenants(c.env.GODX_ISSUER, [myOrgId]),
+    }),
+  }),
+);
+```
+
+Wire contract: **CloudEvents HTTP binding, structured mode** (`application/cloudevents+json`, or
+`-batch+json` for an array) and **Standard Webhooks** signatures (`webhook-id` / `-timestamp` /
+`-signature`, HMAC-SHA256 over `{id}.{timestamp}.{body}`, `whsec_` secrets, ±5 min replay
+tolerance, constant-time verify, multiple space-separated signatures for key rotation).
+
+### Mounting ingest outside Hono
+
+`handleIngestRequest` is `(Request) → Promise<Response>` — pure fetch API, no framework types.
+A plain Workers module (or anything fetch-shaped: Bun, Deno, Node ≥18 with an adapter) mounts it
+directly:
+
+```ts
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === "/api/sync/ingest") {
+      return handleIngestRequest(request, {
+        secret: env.SYNC_WEBHOOK_SECRET,
+        expectedSource: env.GODX_ISSUER,
+        process: createProcessor({ projector, inbox: createD1Inbox(env.DB), families: ["organization"] }),
+      });
+    }
+    return new Response("not found", { status: 404 });
+  },
+};
+```
+
+Keep it **outside** any session/auth middleware: the caller is a bridge, not a browser —
+authentication is the HMAC signature, replay-guarded by the timestamp.
+
+### Inbox DDL (copy-paste)
+
+`D1_INBOX_DDL` exports exactly this — paste it into a migration verbatim and keep any ORM-side
+schema (e.g. Drizzle) in lockstep:
+
+```sql
+CREATE TABLE IF NOT EXISTS godx_sync_inbox (
+  event_id TEXT PRIMARY KEY,
+  sequence INTEGER NOT NULL,
+  applied_at INTEGER NOT NULL
+);
+```
+
+### Pattern: scheduled reconcile (Cron Trigger)
+
+The boilerplate reconciles lazily from a request handler (stale > 5 min). A Worker that must not
+pay that latency on a request can run the same pass from a Cron Trigger instead — guidance, not
+code shipped in this repo:
+
+```jsonc
+// wrangler.jsonc
+"triggers": { "crons": ["*/15 * * * *"] }
+```
+
+```ts
+export default {
+  fetch: app.fetch,
+  async scheduled(_event: ScheduledEvent, env: Env) {
+    const snapshots = createSnapshotClient({
+      issuer: env.GODX_ISSUER,
+      serviceSlug: env.GODX_SERVICE_SLUG,
+      serviceSecret: env.GODX_CLIENT_SECRET,
+    });
+    await snapshots.reconcile("organization", myProjector(drizzle(env.DB)));
+  },
+};
+```
+
+The projector's sequence fence makes the two safe to combine with the event leg in any order —
+snapshot rows carry the page watermark and cannot overwrite newer event-applied state.
+
+### Outcome semantics — every value
+
+| Outcome | Meaning | Recorded in inbox? | HTTP (per batch) |
+|---|---|---|---|
+| `applied` | The projector upserted the row; the event id is now in the inbox. | yes | 200 |
+| `skipped_duplicate` | The CloudEvents `id` was already applied — dedupe hit. Also what copies 2..N of a fanned-out `user` event answer. | already was | 200 |
+| `skipped_stale` | Reserved for a consumer that checks the fence before applying; the current processor lets the SQL fence absorb staleness instead. | — | 200 |
+| `terminated_unknown_type` | Malformed subject, or a family this consumer does not mirror — redelivery cannot make us know it (term, not nak). | no | 200 |
+| `terminated_tenant_refused` | The `TenantPolicy` refused (source, organization) — noise, not an incident. | no | 200 |
+| `retry` | The projector threw — transient until proven otherwise; the sender must redeliver. **Not recorded**, so the redelivery reaches the projector again. | no | **500** for the whole batch |
+
+### Outcome → HTTP mapping (the cross-SDK contract)
+
+| Outcome | HTTP | Sender's move |
+|---|---|---|
+| `applied`, `skipped_duplicate`, `terminated_*` | 200, outcome named per delivery | done — redelivery cannot change a durable answer |
+| any `retry` in the batch | 500 | redeliver the **whole** batch; already-applied rows absorb as `skipped_duplicate` |
+| bad signature | 401 | fix the secret |
+| wrong content type | 415 | send a CloudEvents structured mode |
+| malformed body/envelope | 400 | fix the bytes — redelivering them cannot help |
+| non-POST method | 405 | POST only |
+
+`php-sdk`'s `Sync\Http\WebhookIngest` answers identically (its outcome names differ —
+`duplicate`, `rejected`, `failed` — the HTTP statuses do not).
+
+### Edge-case semantics, stated rather than implied
+
+- **Idempotency** is the CloudEvents `id` (the inbox's key). The inbox records **after** a
+  successful projection, never before — a failure must reach the projector again on redelivery.
+- **Ordering** is the `sequence` fence. A projector must refuse to overwrite newer state (SQL:
+  `... ON CONFLICT DO UPDATE ... WHERE stored.sequence <= incoming.sequence`) because
+  redeliveries and snapshot/stream overlap deliver twice **by design**.
+- **`user` events fan out** — one copy per organization, same `id`, org carried as delivery
+  metadata (`X-Godx-Organization`), never in the envelope. A consumer serving **one** org (an
+  on-premise instance) needs nothing special. A consumer serving **several** orgs through one
+  endpoint must make its projector org-aware before trusting id-level dedupe, since copy 2..N of
+  a `user` event answer `skipped_duplicate`.
+- **Known limitation — concurrent duplicate deliveries**: `createD1Inbox` does
+  seen → apply → record without a transaction, so two simultaneous deliveries of the same event
+  can both reach the projector. The sequence fence makes that harmless for last-write-wins
+  mirrors; a projector with side effects must be idempotent per event id. (php-sdk's SQL inbox
+  runs in a transaction and has a 4-process concurrency test; a D1 `batch()`-based inbox is the
+  fix here when it matters.)
+
+## `./org` — the write-back client
+
+The Delegated Organization API (`/api/org/v1/*`) is the only sanctioned way a service changes
+platform-owned directory data; the identity feed then carries the change back to every consumer.
+Auth is a Bearer token minted for the **`organization-api` recipient resource** (`aud` contains
+`{issuer}/api/org/v1`) by a `user`-lane principal; tenancy is the token's organization,
+re-derived server-side per request — this client never sends an organization id.
+
+### Access model — pick the right principal (house rule)
+
+| Principal | Authority | Use it for |
+|---|---|---|
+| **Mini app** (customer-created) | **Narrow by design**: consent tiers, `MiniAppScopeNarrower`, writes gated behind `write_scopes_enabled_at`. Do NOT design around getting a mini app more power | small customer-owned integrations acting for their signed-in users |
+| **Service launch** (registered downstream service) | acts **as the signed-in human** — `org.*` words survive only where that person's RBAC holds the mapped permission, re-checked on every mint (godx-jp/id#1960) | this client, in request context: writes carry the human's authority and audit trail |
+| **ServiceAccount** (machine identity) | `client_credentials`, per-client scope allowlist, `trust_tier` gates privilege (`internal_agent` + `elevated` is the only path to `admin:*`, super-admin-only) | broad or background access with no human in the loop. Note: `/api/org/v1` admits `prn=user` only — a machine token uses the surfaces its allowlist grants (directory/snapshot reads via the service credential, and whatever the platform grants that account), never this client with a borrowed user token |
+
+If a task seems to need "a mini app with more rights", the answer is a ServiceAccount with the
+right allowlist — never widening the mini app.
+
+**Lane note (updated):** the caveat that only mini-app tokens carried this audience is
+**resolved** — since godx-jp/id#1960 a downstream **service-launch token carries the audience
+when org.\* scopes are granted**, i.e. when at least one delegated `org.*` scope was requested at
+login *and* survived RBAC narrowing (#1958). A launch that asked for no org scope, or whose
+user's RBAC stripped them all, mints exactly the token it minted before — and this surface then
+answers 401.
+
+### Methods
+
+Every write sends an `Idempotency-Key` (generated UUID when not supplied). `all()` returns an
+async iterator that follows page-based pagination to the last page, so callers cannot forget
+page 2.
+
+| Method | HTTP call | Scope required |
+|---|---|---|
+| `me()` | `GET /me` | `org:profile` (membership alone suffices) |
+| `employees.list(page?)` | `GET /employees` | `org.employees:read` |
+| `employees.all()` | `GET /employees` (all pages, async iterator) | `org.employees:read` |
+| `employees.create(payload, idempotencyKey?)` | `POST /employees` | `org.employees:write` |
+| `employees.managerOf(consoleUserId)` | `GET /users/{id}/manager` | `org.employees:read` (deliberately not a scope of its own) |
+| `departments.list(page?)` / `.all()` / `.create(...)` | `GET`/`POST /departments` | `org.departments:read` / `:write` |
+| `branches.list(page?)` / `.all()` / `.create(...)` | `GET`/`POST /branches` | `org.branches:read` / `:write` |
+| `teams.list(page?)` / `.all()` / `.create(...)` | `GET`/`POST /teams` | `org.teams:read` / `:write` |
+
+### Scope → permission mapping
+
+A delegated scope survives RBAC narrowing only when the signing-in user holds **any one** of the
+listed permissions (platform's `OrganizationScopeCatalog` — each entry mirrors the gate the
+equivalent human surface already enforces, so a token can never be a quieter path to something
+the Console refuses):
+
+| Scope | Permission (any one of) |
+|---|---|
+| `org:profile` | — (membership alone) |
+| `org.employees:read`, `org.departments:read`, `org.branches:read`, `org.teams:read` | `organization.view` |
+| `org.employees:write` | `organization.manage`, `settings.manage` |
+| `org.departments:write` | `organization.departments.manage`, `settings.manage` |
+| `org.branches:write` | `organization.branches.manage`, `settings.manage` |
+| `org.teams:write` | `organization.teams.manage` |
+
+### Handling `OrgApiError`
+
+Every non-OK answer throws `OrgApiError` with the standard fields surfaced — switch on `status`
+and read the field made for that status:
+
+```ts
+import { createOrgApi, OrgApiError } from "@godxjp/server-sdk/org";
+
+const orgApi = createOrgApi({ issuer, accessToken });
+try {
+  await orgApi.employees.create({ employee_code: "E-42", full_name: "山田 太郎" });
+} catch (e) {
+  if (!(e instanceof OrgApiError)) throw e;
+  switch (e.status) {
+    case 401: // token missing/expired, or minted without the organization-api audience
+    case 403: // token lacks the route's org.* scope
+      console.warn(e.message, e.wwwAuthenticate); // RFC 6750 challenge, e.g. scope="org.employees:write"
+      break;
+    case 422: // validation refused the payload
+      console.warn(e.validationErrors);           // { employee_code: ["already taken"] }
+      break;
+    case 429: // rate limited
+      await scheduleRetryIn(e.retryAfterSeconds ?? 60);
+      break;
+    default:
+      throw e;
+  }
+}
+```
+
+The error `message` already names the likely cause per status ("missing/expired, or was not
+minted for the organization-api audience", "lacks the route's org.* scope", …) so a bare log is
+still actionable.
+
+## Tests
+
+```bash
+npx vitest run   # from packages/server-sdk
+```
+
+30 tests, doubling as executable behaviour docs:
+
+- `sync.test.ts` (23): envelope validation (specversion/subject/source pinning), webhook
+  sign/verify (tamper, replay, rotation, raw-secret fallback), processor outcomes (duplicate,
+  unknown family, tenant refused, retry-not-recorded), ingest HTTP mapping (single, batch, mixed
+  outcomes, batch-retry, 401/415/400/405), snapshot pagination/contract-stop/410.
+- `org.test.ts` (7): Bearer + Accept headers, Idempotency-Key (generated and caller-supplied),
+  pagination to the last page, 403 `WWW-Authenticate` surfaced, 401 audience hint, 422 per-field
+  validation, 429 `Retry-After`.
+
+The php-sdk mirrors the sync suite in `tests/Sync/Http/`.
+
+## Troubleshooting
+
+Short version — the boilerplate's root `README.md` has the full symptom → cause → fix list.
+
+- **"unexpected aud"** on verify: `audience` must be the ServiceInstance slug, not the service
+  slug. The error message quotes expected vs actual `iss`/`aud`.
+- **401 from `/api/org/v1/*`**: the token lacks the `organization-api` audience — no `org.*`
+  scope requested, RBAC stripped them all, or a pre-#1960 platform. 403 `insufficient_scope`
+  means the audience is there but the route's scope is not — read `wwwAuthenticate`.
+- **TLS "internal error" from workerd** against a Herd-hosted local platform: workerd must trust
+  the Herd CA (`NODE_EXTRA_CA_CERTS`, see the boilerplate's `dev:herd` script).
+- **Ingest answers 401**: same `whsec_` secret on both ends, and the bridge's clock within
+  ±5 min. 415 means the content type is not a CloudEvents structured mode.
+- **Snapshot 403/410**: `service_api_enabled` missing on the credential / cursor expired —
+  restart the pass from the beginning. The thrown error carries the per-status hint.
+
+## Roadmap
+
+- `Transport` (JetStream durable) for Node hosts, feeding the same `Projector`.
+- Extraction to `godx-jp/server-sdk` + npm publication once the surface settles. Publish
+  checklist:
+  - [ ] Compile to `dist/` (tsc) and point `exports` at built JS + `.d.ts` — the conditions
+        currently resolve `.ts` source, which only works inside a workspace.
+  - [ ] Keep the `workerd`/`worker`-before-`browser` condition order in every subpath (see
+        [Package exports](#package-exports--condition-order-is-load-bearing)).
+  - [ ] Ship `browser-guard` in the build and verify a browser-bundler build actually throws.
+  - [ ] `"private": true` → off; add `files`, `license`, `repository`; version from `0.1.0`.
+  - [ ] Move `hono` to `peerDependencies` review (already `>=4`) and keep `jose` as the only
+        runtime dependency.
+  - [ ] CI: `vitest run` (30) + `tsc --noEmit` + a pack-and-import smoke test on Workers and Node.

package/dist/auth.d.ts

@@ -0,0 +1,37 @@
+interface Principal {
+    readonly sub: string;
+    readonly organizationId: string;
+    /** Defaults to read_only unless the claim says full — fail closed. */
+    readonly accessMode: "full" | "read_only";
+    readonly scopes: readonly string[];
+    readonly serviceInstanceId?: string;
+    readonly clientId?: string;
+    /** Unix seconds, from the access token's exp. */
+    readonly expiresAt: number;
+    /** From userinfo, when the adapter fetched it at login. */
+    readonly name?: string;
+    readonly email?: string;
+}
+/**
+ * The one parse gate. Validates signature (JWKS), iss (discovery issuer,
+ * exact), aud (= service slug), exp — then requires organization_id.
+ */
+declare function verifyAccessToken(token: string, opts: {
+    issuer: string;
+    serviceSlug: string;
+    /** The token audience = your ServiceInstance slug. Defaults to serviceSlug. */
+    audience?: string;
+}): Promise<Principal>;
+interface Pkce {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+}
+declare function createPkce(): Promise<Pkce>;
+declare function randomToken(bytes?: number): string;
+/** Encrypt + sign an arbitrary payload into a compact cookie value (JWE dir/A256GCM). */
+declare function sealData(payload: Record<string, unknown>, secret: string, ttlSeconds: number): Promise<string>;
+/** Returns null for anything invalid or expired — never throws on bad input. */
+declare function openData<T = Record<string, unknown>>(token: string, secret: string): Promise<T | null>;
+
+export { type Pkce, type Principal, createPkce, openData, randomToken, sealData, verifyAccessToken };

package/dist/auth.js

@@ -0,0 +1,16 @@
+import {
+  createPkce,
+  openData,
+  randomToken,
+  sealData,
+  verifyAccessToken
+} from "./chunk-GPGSVZCR.js";
+import "./chunk-DMXYEWYY.js";
+export {
+  createPkce,
+  openData,
+  randomToken,
+  sealData,
+  verifyAccessToken
+};
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/authorization.d.ts

@@ -0,0 +1,16 @@
+interface EffectiveAccess {
+    permissions: string[];
+    roles: string[];
+    serviceAccess: Record<string, unknown>;
+    contractVersion?: string;
+    evaluatedAt?: string;
+    authoritative: boolean;
+}
+declare function fetchEffectivePermissions(params: {
+    issuer: string;
+    accessToken: string;
+    organizationId: string;
+    branchId?: string;
+}): Promise<EffectiveAccess>;
+
+export { type EffectiveAccess, fetchEffectivePermissions };

package/dist/authorization.js

@@ -0,0 +1,31 @@
+import {
+  GodxHttpError
+} from "./chunk-DMXYEWYY.js";
+
+// src/authorization.ts
+async function fetchEffectivePermissions(params) {
+  const url = new URL("/api/sso/me/permissions", params.issuer);
+  url.search = new URLSearchParams({
+    organization_id: params.organizationId,
+    ...params.branchId ? { branch_id: params.branchId } : {}
+  }).toString();
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${params.accessToken}` }
+  });
+  if (!res.ok) {
+    throw new GodxHttpError(res.status, await res.text(), "effective permissions failed");
+  }
+  const body = await res.json();
+  return {
+    permissions: body.permissions ?? [],
+    roles: body.roles ?? [],
+    serviceAccess: body.service_access ?? {},
+    contractVersion: body.contract_version,
+    evaluatedAt: body.evaluated_at,
+    authoritative: body.authoritative === true
+  };
+}
+export {
+  fetchEffectivePermissions
+};
+//# sourceMappingURL=authorization.js.map

package/dist/authorization.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/authorization.ts"],"sourcesContent":["/**\n * ./authorization — effective-access read model. Mirrors php-sdk's\n * Authorization module: results carry the platform's authoritative flag,\n * nothing is cached as a positive grant here.\n */\nimport { GodxHttpError } from \"./http\";\n\nexport interface EffectiveAccess {\n  permissions: string[];\n  roles: string[];\n  serviceAccess: Record<string, unknown>;\n  contractVersion?: string;\n  evaluatedAt?: string;\n  authoritative: boolean;\n}\n\nexport async function fetchEffectivePermissions(params: {\n  issuer: string;\n  accessToken: string;\n  organizationId: string;\n  branchId?: string;\n}): Promise<EffectiveAccess> {\n  const url = new URL(\"/api/sso/me/permissions\", params.issuer);\n  url.search = new URLSearchParams({\n    organization_id: params.organizationId,\n    ...(params.branchId ? { branch_id: params.branchId } : {}),\n  }).toString();\n\n  const res = await fetch(url, {\n    headers: { Authorization: `Bearer ${params.accessToken}` },\n  });\n  if (!res.ok) {\n    throw new GodxHttpError(res.status, await res.text(), \"effective permissions failed\");\n  }\n  const body = (await res.json()) as {\n    permissions?: string[];\n    roles?: string[];\n    service_access?: Record<string, unknown>;\n    contract_version?: string;\n    evaluated_at?: string;\n    authoritative?: boolean;\n  };\n  return {\n    permissions: body.permissions ?? [],\n    roles: body.roles ?? [],\n    serviceAccess: body.service_access ?? {},\n    contractVersion: body.contract_version,\n    evaluatedAt: body.evaluated_at,\n    authoritative: body.authoritative === true,\n  };\n}\n"],"mappings":";;;;;AAgBA,eAAsB,0BAA0B,QAKnB;AAC3B,QAAM,MAAM,IAAI,IAAI,2BAA2B,OAAO,MAAM;AAC5D,MAAI,SAAS,IAAI,gBAAgB;AAAA,IAC/B,iBAAiB,OAAO;AAAA,IACxB,GAAI,OAAO,WAAW,EAAE,WAAW,OAAO,SAAS,IAAI,CAAC;AAAA,EAC1D,CAAC,EAAE,SAAS;AAEZ,QAAM,MAAM,MAAM,MAAM,KAAK;AAAA,IAC3B,SAAS,EAAE,eAAe,UAAU,OAAO,WAAW,GAAG;AAAA,EAC3D,CAAC;AACD,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,IAAI,cAAc,IAAI,QAAQ,MAAM,IAAI,KAAK,GAAG,8BAA8B;AAAA,EACtF;AACA,QAAM,OAAQ,MAAM,IAAI,KAAK;AAQ7B,SAAO;AAAA,IACL,aAAa,KAAK,eAAe,CAAC;AAAA,IAClC,OAAO,KAAK,SAAS,CAAC;AAAA,IACtB,eAAe,KAAK,kBAAkB,CAAC;AAAA,IACvC,iBAAiB,KAAK;AAAA,IACtB,aAAa,KAAK;AAAA,IAClB,eAAe,KAAK,kBAAkB;AAAA,EACxC;AACF;","names":[]}

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/browser-guard.js

@@ -0,0 +1,5 @@
+// src/browser-guard.ts
+throw new Error(
+  "@godxjp/server-sdk was imported into a browser bundle. It holds service credentials and must only run server-side (Workers/Node). Use @godxjp/web-sdk in frontend code."
+);
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/browser-guard.ts"],"sourcesContent":["// Resolved instead of the real module when a bundler builds for the browser.\n// This SDK holds service credentials (client_secret, session secret); it must\n// only ever run server-side. For browser code use @godxjp/web-sdk.\nthrow new Error(\n  \"@godxjp/server-sdk was imported into a browser bundle. \" +\n    \"It holds service credentials and must only run server-side (Workers/Node). \" +\n    \"Use @godxjp/web-sdk in frontend code.\",\n);\n\nexport {};\n"],"mappings":";AAGA,MAAM,IAAI;AAAA,EACR;AAGF;","names":[]}