Installation

The current release is permdock@0.1.0. See the roadmap for what is planned and how versions are numbered.

PackagesCopy Anchor Link

pnpm add permdock

permdock is the only package. It is published by the scaledockhq npm organisation.

npm and yarn work the same way; the repository itself uses pnpm workspaces.

RequirementsCopy Anchor Link

• Node.js 24 or later for servers and the CLI. The package declares engines.node: ">=24". Browser and React Native bundles are produced from the same ESM entry points and do not depend on Node.
• TypeScript 7. PermDock is written in and built with TypeScript 7, and the public API avoids template-literal unions so TypeScript 7 stays fast: permissions are typed object references, not string unions. The type tests in tests/types also check the public types under TypeScript 5.9 and 6, so an app that has not moved yet keeps compiling.
• ESM only. There is no CommonJS build. Your tsconfig.json needs a moduleResolution that understands package exports (bundler, node16 or nodenext) so subpath imports such as permdock/react resolve.
• Runtime entries depend on @standard-schema/spec only, and it is types only. The package's other dependencies (oxc-parser, citty, jiti, smol-toml, package-manager-detector, @clack/prompts, diff) belong to the CLI and no runtime entry loads them.

RuntimesCopy Anchor Link

Core uses only the WinterTC Minimum Common API (fetch, Request, Response, URL, crypto.subtle, TextEncoder, structuredClone) and no Node built-ins, no AsyncLocalStorage, no module-level state. That is by construction (invariants 7 and 12 in AGENTS.md) and a conformance test in tests/bundle asserts it: every client entry and permdock/server must load in a bare WinterTC-shaped global. The table lists what each runtime adds or lacks; nothing in it changes how a decision is made.

The one runtime-specific caveat is state: any store or sink that defaults to memory (memoryApprovalStore, memorySink) is per process or per isolate and resets on cold start. permdock doctor warns when the memory store is the configured ApprovalStore in a serverless target. Recipes for Durable Objects, KV, Redis and Postgres stores live on the approvals and audit and observability pages; none is a package.

A Standard Schema validatorCopy Anchor Link

Resources are defined from any validator that implements Standard Schema. Bring the one you already use:

pnpm add zod      # or
pnpm add valibot  # or
pnpm add arktype

PermDock never imports a validator itself. resource(Post, ...) reads Post['~standard'] to infer the instance type and to validate untrusted input at trust boundaries (see validation). Boundary validation is synchronous, so a schema whose validate returns a Promise produces a typed PermDockValidationError instead of a silent deny.

Subpath exportsCopy Anchor Link

All adapters live in the one permdock package. Import only what a bundle needs; nothing from a server entry is reachable from a client entry.

The full matrix with example apps and related standards is on the adapters index.

Optional peersCopy Anchor Link

Runtime entries have no dependency beyond @standard-schema/spec. A few entries verify material or talk to a vendor SDK and declare an optional peer instead of bundling it, and a few CLI commands do the same:

Why runtime entries have no dependenciesCopy Anchor Link

Core runs in browsers, React Native, edge functions, serverless functions, MCP servers and Node, and every dependency it carries is paid by all of them. So every runtime entry imports exactly one package, @standard-schema/spec. It is types only, and it is a real dependency rather than vendored types because resource definitions take a StandardSchemaV1, which makes it part of the public API that should version with the spec.

• No validator. A bundled Zod would lock out Valibot and ArkType users and add tens of kilobytes to clients that never call it.
• No serialiser. Conditions and snapshots are plain JSON with tagged ISO date strings, one format that works in Postgres, snapshots and catalogs, so there is no superjson.
• No telemetry. OpenTelemetry lives in permdock/otel behind a type-only Tracer interface rather than as a required peer.
• ESM only. The target runtimes are ESM, and a dual CommonJS build would double the test matrix and bring the dual-package hazard.
• Tooling never reaches a runtime entry: the CLI and the test runners ship in the same package, but no runtime entry imports them. The one CLI dependency, oxc-parser (about 3.5 MB installed with one platform binding), is what collect, doctor and the build hooks need; yaml and ajv are bundled into the lazily loaded OpenAPI command chunks, and the Postgres parser, pg, unplugin and Vitest are optional peers.

There is no size cap chosen in advance. tests/bundle measures the min+gzip size of every entry, and the measured size is the regression baseline: a test compares every entry against the recorded baseline, so a size change fails CI until the baseline is updated in the same PR, where review sees it. Core stays small because of the rules above, not because of a number picked from a competitor's bundle, so features such as the condition AST or the Decision shape are never cut to meet a guess.

TypeScript configurationCopy Anchor Link

A minimal tsconfig.json that works with the subpath exports and keeps inference fast:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "exactOptionalPropertyTypes": true,
    "skipLibCheck": true
  }
}

strict matters: subject narrowing through assert and the actions / collection arity checks rely on strict null checks. The library itself is built with isolatedDeclarations and erasableSyntaxOnly, so its declaration files contain no inferred-only types and load quickly.

Where files goCopy Anchor Link

The quick start fills in the first three.

Verify the installCopy Anchor Link

pnpm permdock doctor

doctor checks the TypeScript version, module resolution, that exactly one copy of permdock is installed, that no server entry is imported from a client file, that memoryApprovalStore() is not the store in a serverless deployment that surfaces approvals, that PERMDOCK_CLOUD_* variables (when present) are server-only and reach the API, and that the catalog produced by permdock collect is fresh. The permdock-wire skill runs it as soon as the three files exist.

Next stepsCopy Anchor Link

• Quick start: define, grant, check, guard.
• Larger apps: per-feature definitions, mergePermissions, permdock collect.
• Naming: why every adapter exports createPermDock.