@canopy-io/node 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Official TypeScript SDK for [Canopy](https://canopy-io.com) — hierarchical identity and access management for B2B SaaS.
 
-> **Status: 0.1.0.** The client, pagination and the four main resources are built and tested. 27 of 81 operations have a typed wrapper; the rest are reachable through `canopy.client.request` with the same envelope handling, error typing and retry policy.
+This package is the client. It calls Canopy's API, and it verifies the access tokens Canopy issues.
 
 ## Install
 
@@ -14,6 +14,22 @@ Requires Node 18 or later. Ships ESM and CommonJS, and has **zero runtime depend
 
 Despite the name, it is not Node-only: the client is `fetch` and nothing else, so the same build runs in browsers, on Cloudflare Workers and on Deno.
 
+## Features
+
+- **Typed resource wrappers** for `permissions`, `identities`, `roles` and `assignments` — the four every integration touches.
+- **The whole API, typed.** Any operation without a wrapper is reachable through `canopy.client.request` with the same envelope handling, error typing and retry policy.
+- **Both credential types.** An API key (`cnpy_…`, sent as `X-API-Key`) for server-to-server calls, or an identity or portal JWT sent as a bearer token.
+- **Envelope unwrapping.** All five response shapes are handled, so a call returns the payload rather than a wrapper.
+- **Pagination as an async iterator.** One `for await` loop covers both the offset and cursor styles, and `paginate` exposes the same machinery for anything hand-rolled.
+- **A retry policy that knows what is safe to replay** — idempotent methods and 429s only, with `Retry-After` honoured and capped.
+- **Concurrency and idempotency headers.** `withConcurrency` carries a resource's `version` as `If-Match`; `Idempotency-Key` is accepted on the bulk endpoints that support it.
+- **Typed errors.** `CanopyError` carries a stable `code`, `CanopyConnectionError` marks a transport failure, `CanopyTokenError` a rejected token, `CanopyAuthorizerError` a check that could not be decided — each with a type guard.
+- **Local access-token verification.** `TokenVerifier` checks Canopy's RS256 signatures against the published key set: one JWKS fetch, then no network on any verification after it.
+- **Local authorization.** `LocalAuthorizer` answers permission checks in-process from an identity's grant roots and a shared copy of your hierarchy, so a check costs a walk up the tree rather than a round trip.
+- **Conditional reads.** `requestConditional` sends the validator you already hold and tells you whether anything changed, so something expensive can be held and revalidated cheaply.
+- **Deadlines and cancellation.** A per-attempt timeout and a caller's own `AbortSignal`, settable client-wide or per call.
+- **Types generated from the published spec**, with CI failing on drift.
+
 ## Usage
 
 ```ts
@@ -50,8 +66,7 @@ try {
 }
 ```
 
-Anything without a typed wrapper is still reachable, with the same envelope
-handling and retry policy:
+Anything without a typed wrapper is reachable the same way, with the same envelope handling and retry policy:
 
 ```ts
 const page = await canopy.client.request("GET", "/api/v1/audit-events", {
@@ -59,55 +74,106 @@ const page = await canopy.client.request("GET", "/api/v1/audit-events", {
 });
 ```
 
-## Design
+### Verifying an access token
 
-Three decisions shape this package.
+Authorization asks the API a question. Authentication does not: Canopy signs
+access tokens RS256 and publishes the keys, so a token is checked locally —
+one JWKS fetch, then no network on any verification after it.
 
-**Types are generated from the published spec, never hand-written.**
-`src/generated/types.ts` comes from <https://canopy-io.com/openapi/api.json>, the same document that renders Canopy's API reference. `npm run generate:check` fails if the committed types no longer match the live spec, so the SDK cannot silently describe an API that has moved on.
+```ts
+import { TokenVerifier, isCanopyTokenError } from "@canopy-io/node";
 
-**Zero runtime dependencies.**
-The client is `fetch` and nothing else, so it runs unchanged on Node, in browsers, on Cloudflare Workers, and on Deno — and it adds no supply-chain surface to anything that installs it. CI fails if a runtime dependency appears.
+const verifier = new TokenVerifier();
 
-**The hand-written layer exists for correctness, not convenience.**
-Writing a `fetch` call against a documented REST API is easy, and an LLM will do it for you. What neither gets reliably right is the part this package owns:
+try {
+  const claims = await verifier.verify(bearerToken);
 
-- **Which operations are safe to retry.** GET, HEAD, PUT and DELETE are idempotent by HTTP definition and are retried on a 5xx; POST is not, and a blind retry there can create a second role assignment. A 429 is retried regardless, because the request was refused before anything happened.
-- **Two pagination styles behind one shape.** The audit log is cursor-paginated; everything else is offset. The top-level response is identical either way, so a hand-rolled loop silently reads only the first page of one of them — or never terminates.
-- **The five-shape response envelope.** `{ data }`, `{ items }`, `{ items, pagination }`, `{ summary, results }` for partial success, `{ error }`, and bare 204.
-- **Typed error codes.** `catch (e) { if (e.code === "rbac.assignment_conflict") }` branches on a contract rather than on a message that may be reworded.
-- **Webhook signature verification.** Security-critical, and easy to get subtly wrong — timing-unsafe comparison, missing timestamp check. _(Not built yet — see the roadmap.)_
+  claims.sub; // the identity or user id
+  claims.type; // "identity" | "user" | "api_key" | "platform"
+  claims.environment_id; // present on identity tokens
+} catch (error) {
+  if (isCanopyTokenError(error)) {
+    // Every code here means 401 to the caller who presented the token.
+    // `error.code` is for your logs: token.expired, token.signature_invalid,
+    // token.issuer_mismatch, and so on.
+  }
 
-## Roadmap
+  throw error;
+}
+```
 
-- [x] Package scaffold, dual ESM/CJS build, generated types
-- [x] Client core — auth, envelope unwrapping, typed errors, retry
-- [x] Pagination — one async iterator covering offset and cursor
-- [x] Resource wrappers — `permissions`, `identities`, `roles`, `assignments`
-- [x] Spec-drift guard — fails when the API's surface changes
-- [ ] Webhook signature verification
+Hosted Login tokens carry an audience, so name your client. Direct API tokens
+carry none and need no option — and a token that has an `aud` is refused
+rather than ignored when you have not said which client you are:
 
-Other languages are deliberately **not** planned here. Point your own generator at the published spec — that serves Python, Go and the rest better than a partly-maintained SDK would.
+```ts
+new TokenVerifier({ audience: process.env.CANOPY_OAUTH_CLIENT_ID });
+```
 
-## Contributing
+Self-hosted instances set `issuer`. Getting it wrong fails closed: tokens are
+rejected, never mistakenly accepted.
 
-```bash
-npm ci
-npm run verify   # lint, typecheck, spec drift, test, build
-```
+### Authorizing without a call per request
 
-To work against an unreleased API, point the generator somewhere else:
+Asking "may this identity act _here_" on every request puts Canopy in your
+request path forever. `LocalAuthorizer` asks the other question — "**where** may
+it act" — once, and answers everything after that in-process.
 
-```bash
-CANOPY_SPEC_URL=../canopy/apps/canopy-api/spec/openapi.api.json npm run generate
-```
+```ts
+import { Canopy, LocalAuthorizer } from "@canopy-io/node";
 
-Releases use [changesets](https://github.com/changesets/changesets). Include one in your PR:
+const canopy = new Canopy({ apiKey: process.env.CANOPY_API_KEY });
+const authorizer = new LocalAuthorizer(canopy.client);
 
-```bash
-npm run changeset
+const { allowed } = await authorizer.evaluate({
+  identity_id: identityId,
+  permission: "reports.view",
+  node_id: nodeId,
+});
 ```
 
+It holds two things: the identity's grant roots, and one copy of your hierarchy
+— read as parent edges from `GET /api/v1/nodes/parents` rather than the full
+tree, which is 3.7x smaller — shared across every identity in the process. A check walks up from the node in
+question looking for a grant root — a grant already means _this node and
+everything beneath it_, so the roots are never expanded into their descendants.
+
+Both are held for at most 60 seconds, which is the delay between an access
+change and it taking effect, including a moved node. Set `ttlMs` to change it,
+knowing that shortening it below the gap between a user's requests saves
+nothing — every request then finds the cache expired and refetches.
+
+`canopy.permissions.evaluate` remains for a decision with no staleness at all.
+
+The credential needs to be able to read both halves. A `full_access` API key
+already can; a **scoped** one must list `identity.view` (the grant roots) and
+`hierarchy.view` (the tree). Without the latter the tree endpoint answers an
+empty tree and a `200` — it is telling you what you may see, which is nothing —
+so a node-scoped check raises `CanopyAuthorizerError` rather than returning
+`false`. Not being able to see the hierarchy is not the same as the identity
+lacking the permission, and answering `false` there would deny every
+node-scoped request while looking entirely healthy.
+
+## What the hand-written layer is for
+
+Writing a `fetch` call against a documented REST API is easy, and an LLM will do it for you. What neither gets reliably right is the part this package owns:
+
+- **Which operations are safe to retry.** GET, HEAD, PUT and DELETE are idempotent by HTTP definition and are retried on a 5xx; POST is not, and a blind retry there can create a second role assignment. A 429 is retried regardless, because the request was refused before anything happened. A caller's own cancellation is never retried — aborting a `signal` rejects with that abort, while timeouts and transport failures throw `CanopyConnectionError`.
+- **The protocol headers that make a write safe.** `If-Match` carries a resource's current `version`, so a concurrent edit answers 409 instead of being silently overwritten; `Idempotency-Key` makes a replayed bulk create return the original result rather than creating rows twice.
+- **Two pagination styles behind one shape.** The audit log is cursor-paginated; everything else is offset. The top-level response is identical either way, so a hand-rolled loop silently reads only the first page of one of them — or never terminates.
+- **The five-shape response envelope.** `{ data }`, `{ items }`, `{ items, pagination }`, `{ summary, results }` for partial success, `{ error }`, and bare 204.
+- **Typed error codes.** `catch (e) { if (e.code === "rbac.assignment_conflict") }` branches on a contract rather than on a message that may be reworded.
+- **The traps in verifying a token.** Pinning the algorithm so `alg: none` and HMAC key-confusion cannot get in, bounding `kid`-triggered refetches so a forged header cannot hammer the issuer, refusing to ignore an `aud` the token carries, and refusing a **pre-auth** token — genuine, correctly signed, and issued before the user picked an Account, so treating it as a session is a privilege escalation.
+- **The traps in caching an authorization answer.** Holding grant roots rather than expanded node lists, so the cache does not grow with your tree and is not largest for the administrators who have the most access. Revalidating the hierarchy on the same cadence as the grants, because a moved node changes what an inherited grant reaches while the grant itself stays untouched. Sharing one in-flight read across concurrent requests, so a cold start under load does not fan out into the per-request traffic the cache exists to remove. And never serving a held answer past its window to ride out an outage, which would extend the revocation window without anyone choosing to.
+
+## Design
+
+**Types are generated from the published spec, never hand-written.**
+`src/generated/types.ts` comes from <https://canopy-io.com/openapi/api.json>, the same document that renders Canopy's API reference. `npm run generate:check` fails if the committed types no longer match the live spec, so the SDK cannot silently describe an API that has moved on.
+
+**Zero runtime dependencies.**
+The client is `fetch` and nothing else, so it runs unchanged on Node, in browsers, on Cloudflare Workers, and on Deno — and it adds no supply-chain surface to anything that installs it. CI fails if a runtime dependency appears.
+
 ## License
 
 MIT © Canopy Identity Inc.