theAuth 1.2.0

Quickstart · Docs · npm · Go · Discussions

---

theAuth 1.2.0

Open-source authentication and authorization for AI agents, MCP servers and apps. Agent identity, delegation, an OAuth 2.1 authorization server for MCP, DPoP, passkeys, SSO and SCIM in TypeScript. Self-hosted and MIT licensed.

Features and changes

• Agent accountability, enforced before the action runs. (details in the package changelog)
• agent.revoke() now revokes every active delegation chain where the agent is the source or the target, and the chains downstream of them. It returns the revoked chain ids as revokedDelegations and writes one agent.cascade.revoked audit row that joins the hash chain.
• Added guardTool and guardTools, which put the policy engine in front of any agent tool with an execute function, with no framework dependency. A denied call throws ToolDeniedError, a call that needs a human throws ToolApprovalRequiredError with the approval request id and tier, and a failed check throws ToolGuardFailedError. The tool never runs in those cases. Pass the approvalId option to retry an approved call: the guard hands it to evaluate, which spends it once. The PolicyEngineConfig type is now exported from the package root.
• Added signed audit checkpoints and portable receipts. createCheckpoint builds an RFC 6962 style Merkle tree over the chained audit rows and signs the tree head with Ed25519. createInclusionProof, createConsistencyProof and createReceipt produce proofs that verifyInclusionProof, verifyConsistencyProof and verifyReceipt check offline with only a public key. A receipt reveals the decision fields you pick and keeps the rest as salted commitments. Includes generateCheckpointKeyPair, createEd25519Signer, and a CheckpointStore interface with createMemoryCheckpointStore.
• authorize() and policy.evaluate() now accept an optional approvalId. When the matched permission requires approval, the call verifies that the approval request is approved, belongs to the same agent, matches the action and resource exactly, is not expired and was not used, then spends it with a single conditional update and allows the call. Failures are denied with APPROVAL_NOT_FOUND, APPROVAL_NOT_APPROVED, APPROVAL_MISMATCH, APPROVAL_EXPIRED or APPROVAL_ALREADY_USED. The audit row records approver_id and the approval id. A nullable consumed_at column is added to the approval requests table automatically.
• Added resolveActorAgentId and allowUnmappedActors to the MCP config. The live delegation check can now map each actor in a token's act chain (and the token subject) to the agent id used in delegation records before it looks up the link, so the built-in createDbDelegationStore works when token exchange sets act.sub to a user or client id. An actor the mapper returns undefined for rejects the token with INVALID_TOKEN ("unmapped actor") unless allowUnmappedActors is true, and a mapper that throws always rejects. Without a mapper nothing changes. checkLiveDelegation now takes an options object as its fourth argument in place of the now date.
• MCP: new opt-in delegationStore config that re-checks a token's act delegation chain against live link records in validateAccessToken. A missing, revoked or expired link rejects the token with INVALID_TOKEN, so revoking a parent grant no longer leaves tokens minted down the chain valid until exp. Adds createDbDelegationStore(db) and the McpDelegationStore and McpDelegationLink types. Default behaviour is unchanged when not configured.
• Add policy shrink: analyzeUsage compares an agent's effective permissions (including active delegations) with its recorded decisions, suggestShrink proposes a smaller set (with optional, bounded generalization), and verifyShrink and previewPolicyChange report which recorded decisions would flip for any proposed permission change. Reads audit rows in pages and never changes permissions.
• Added a taint-aware (information flow) tool guard. Tool arguments can carry provenance labels, given through the new provenance and tracker options of guardTool/guardTools, through tainted() values, or through a ProvenanceTracker that registers tool results as tool_output:<tool>. A new policy.taint config restricts which labels may flow into which tools with forbid and require rules, per tool or per argument, and either escalates for approval (reusing the single use approvalId flow) or denies with POLICY_TAINT_VIOLATION. The labels and the verdict are written to the hash chained decision record's input_provenance automatically. Behavior with no labels supplied is unchanged. New helpers: tainted, untaint, labelsOf, deriveLabels, matchLabel, ProvenanceTracker.

Fixes

• Delegation constraints now fail closed when a child's argument patterns, IP allowlist or time window do not overlap the parent's. Before, the parent's wider value was kept and the child's restriction was silently dropped. The narrowed result now denies every call. Overnight time windows that are not identical to the other window also deny instead of falling back to the parent's.
• policy.evaluate now denies revoked, suspended and expired agents with POLICY_AGENT_INACTIVE. Requests that arrive with an agent token were already rejected once the agent was revoked, but evaluate takes an agent id directly and never read the agent's status, so a revoked agent could still be allowed by a matching permission. If you gate actions with evaluate, upgrade.
• Security fix: the policy engine now fails closed on several constraint edge cases. maxCallsPerHour: 0 denies every call instead of meaning no limit. IPv4 allowlist parsing rejects octets such as 1abc. allowedArgPatterns checks strings nested in objects and arrays, and an invalid pattern denies instead of throwing. Time windows must be HH:MM, support overnight ranges (start after end), and a malformed window denies. policy.evaluate denies an agent id with no matching row with POLICY_AGENT_NOT_FOUND. A throwing afterAuthorize or onViolation hook no longer causes an unhandled rejection. Delegation chain limits no longer spread large arrays into Math.min.
• Session and audit correctness fixes. Session refresh now creates the replacement before deleting the old session, and a concurrent refresh that loses the race no longer leaves two live sessions. maxConcurrent is re-checked after insert, so concurrent sign-ins cannot exceed the cap (a racer that loses is dropped and create() throws MultiSessionLimitError). A failing audit write no longer makes authorize() throw. When the delegated fallback runs, one audit row is written for the final result instead of an orphan row per path. canonicalJson rejects reference cycles and serializes BigInt. Rate limit windows are parsed once at construction, a zero window is rejected, and the client_id body scan reads at most 8 KB.

Packages in this release

Package	Version	Changelog
@glinr/theauth	1.1.2 to 1.2.0	CHANGELOG
@glinr/theauth-cli	1.1.2 to 1.1.3	CHANGELOG
theauth	0.2.4 to 0.2.5	CHANGELOG

Install

npm install @glinr/theauth@1.2.0
pnpm add @glinr/theauth@1.2.0
yarn add @glinr/theauth@1.2.0
bun add @glinr/theauth@1.2.0

Resources

• Quickstart and agent identity
• MCP OAuth 2.1 and DPoP
• Stability and versioning
• Migration guides
• Go library (releases)
• Questions and ideas: GitHub Discussions
• Security reports: SECURITY.md

Full changelog: v1.1.2...v1.2.0