@authorbot/domain 0.1.0

package/dist/overrides.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+import { uuidv7Schema, } from "@authorbot/schemas";
+import { canTransitionAnnotation } from "./annotation-state.js";
+import { ALLOWED, denied } from "./decision.js";
+import { transitionWorkItem } from "./work-item-state.js";
+/**
+ * Maintainer overrides (Phase 3 contract section 4; design section 11.2).
+ * All four are maintainer-only, require a recorded `reason`, and are recorded
+ * as decisions with `override_reason`. Force-create bypasses the rule but
+ * respects the same uniqueness key `(source_annotation_id, action_type,
+ * rule_version)` with `rule_version: 0`.
+ */
+/** Minimum meaningful override reason length (after trimming). */
+export const MIN_OVERRIDE_REASON_LENGTH = 3;
+/** Bound chosen for storage sanity (not contract-pinned). */
+export const MAX_OVERRIDE_REASON_LENGTH = 2000;
+export const overrideReasonSchema = z
+    .string()
+    .transform((value) => value.trim())
+    .refine((value) => value.length >= MIN_OVERRIDE_REASON_LENGTH, `reason must be at least ${MIN_OVERRIDE_REASON_LENGTH} characters`)
+    .refine((value) => value.length <= MAX_OVERRIDE_REASON_LENGTH, `reason must be at most ${MAX_OVERRIDE_REASON_LENGTH} characters`);
+/** `rule_version` recorded by force-created decisions (contract section 4). */
+export const FORCE_CREATE_RULE_VERSION = 0;
+/** Override 1: reject an open suggestion. */
+export const rejectSuggestionCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+    reason: overrideReasonSchema,
+});
+/** Override 2: cancel a `ready` work item. */
+export const cancelWorkItemCommandSchema = z.strictObject({
+    workItemId: uuidv7Schema,
+    reason: overrideReasonSchema,
+});
+/** Override 3: reopen a rejected suggestion. */
+export const reopenSuggestionCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+    reason: overrideReasonSchema,
+});
+/**
+ * Override 4: force-create a work item bypassing the rule. `work_type` is not
+ * part of the command — it resolves from the annotation scope exactly as
+ * rule-created items do (Phase 3 contract section 3).
+ */
+export const forceCreateWorkItemCommandSchema = z.strictObject({
+    annotationId: uuidv7Schema,
+    reason: overrideReasonSchema,
+});
+function requireMaintainer(actorRole) {
+    if (actorRole !== "maintainer") {
+        return denied("not-maintainer", "only a maintainer may perform overrides");
+    }
+    return ALLOWED;
+}
+function requireSuggestion(kind) {
+    if (kind !== "suggestion") {
+        return denied("not-a-suggestion", "this override applies to suggestions only");
+    }
+    return ALLOWED;
+}
+/** Reject an open suggestion (`open -> rejected`). */
+export function authorizeRejectSuggestion(input) {
+    const maintainer = requireMaintainer(input.actorRole);
+    if (!maintainer.allowed)
+        return maintainer;
+    const suggestion = requireSuggestion(input.annotationKind);
+    if (!suggestion.allowed)
+        return suggestion;
+    if (!canTransitionAnnotation(input.annotationStatus, "rejected")) {
+        return denied("illegal-transition", `a suggestion with status "${input.annotationStatus}" cannot be rejected (only "open")`);
+    }
+    return ALLOWED;
+}
+/** Reopen a rejected suggestion (`rejected -> open`). */
+export function authorizeReopenSuggestion(input) {
+    const maintainer = requireMaintainer(input.actorRole);
+    if (!maintainer.allowed)
+        return maintainer;
+    const suggestion = requireSuggestion(input.annotationKind);
+    if (!suggestion.allowed)
+        return suggestion;
+    if (!canTransitionAnnotation(input.annotationStatus, "open")) {
+        return denied("illegal-transition", `a suggestion with status "${input.annotationStatus}" cannot be reopened (only "rejected")`);
+    }
+    return ALLOWED;
+}
+/** Cancel a `ready` work item (contract section 4: cancel before integration). */
+export function authorizeCancelWorkItem(input) {
+    const maintainer = requireMaintainer(input.actorRole);
+    if (!maintainer.allowed)
+        return maintainer;
+    return transitionWorkItem(input.workItemStatus, "cancelled");
+}
+/**
+ * Force-create a work item for an open suggestion, bypassing the rule. The
+ * annotation must still be able to make the `open -> work_item_created`
+ * transition; uniqueness (one item per annotation/action/rule-version) is the
+ * DB constraint's job.
+ */
+export function authorizeForceCreateWorkItem(input) {
+    const maintainer = requireMaintainer(input.actorRole);
+    if (!maintainer.allowed)
+        return maintainer;
+    const suggestion = requireSuggestion(input.annotationKind);
+    if (!suggestion.allowed)
+        return suggestion;
+    if (!canTransitionAnnotation(input.annotationStatus, "work_item_created")) {
+        return denied("illegal-transition", `a suggestion with status "${input.annotationStatus}" cannot receive a work item (only "open")`);
+    }
+    return ALLOWED;
+}
+//# sourceMappingURL=overrides.js.map

package/dist/scopes.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { type Decision } from "./decision.js";
+/**
+ * Known scopes and role -> scope-bundle mapping (Phase 2 contract section 3,
+ * design section 19.3). `votes:write` (design section 19.2) is deferred with
+ * voting to Phase 3 and is intentionally not a known scope in this phase.
+ */
+export declare const SCOPES: readonly ["chapters:read", "annotations:read", "annotations:write", "work:read", "work:claim", "submissions:write", "tokens:manage", "members:manage"];
+export type Scope = (typeof SCOPES)[number];
+export declare const scopeSchema: z.ZodEnum<{
+    "chapters:read": "chapters:read";
+    "annotations:read": "annotations:read";
+    "annotations:write": "annotations:write";
+    "work:read": "work:read";
+    "work:claim": "work:claim";
+    "submissions:write": "submissions:write";
+    "tokens:manage": "tokens:manage";
+    "members:manage": "members:manage";
+}>;
+export declare const ROLES: readonly ["reader", "contributor", "editor", "maintainer"];
+export type Role = (typeof ROLES)[number];
+export declare const roleSchema: z.ZodEnum<{
+    reader: "reader";
+    contributor: "contributor";
+    editor: "editor";
+    maintainer: "maintainer";
+}>;
+/** Role -> scope bundle (contract section 3). Bundles are cumulative. */
+export declare const ROLE_SCOPES: Readonly<Record<Role, readonly Scope[]>>;
+/** The scope bundle a membership role grants (human sessions use this directly). */
+export declare function roleScopes(role: Role): readonly Scope[];
+/**
+ * An agent's effective scopes = token.scopes ∩ its membership role bundle
+ * (contract section 3). Result is deduplicated and in canonical SCOPES order.
+ */
+export declare function effectiveScopes(tokenScopes: readonly Scope[], role: Role): Scope[];
+export type ScopeDenialReason = "missing-scope";
+/** Require a single scope among the actor's effective scopes. */
+export declare function requireScope(actorScopes: readonly Scope[], required: Scope): Decision<ScopeDenialReason>;
+/** Require every listed scope (denies on the first missing one, in SCOPES order). */
+export declare function requireScopes(actorScopes: readonly Scope[], required: readonly Scope[]): Decision<ScopeDenialReason>;
+//# sourceMappingURL=scopes.d.ts.map

package/dist/scopes.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { ALLOWED, denied } from "./decision.js";
+/**
+ * Known scopes and role -> scope-bundle mapping (Phase 2 contract section 3,
+ * design section 19.3). `votes:write` (design section 19.2) is deferred with
+ * voting to Phase 3 and is intentionally not a known scope in this phase.
+ */
+export const SCOPES = [
+    "chapters:read",
+    "annotations:read",
+    "annotations:write",
+    "work:read",
+    "work:claim",
+    "submissions:write",
+    "tokens:manage",
+    "members:manage",
+];
+export const scopeSchema = z.enum(SCOPES);
+export const ROLES = ["reader", "contributor", "editor", "maintainer"];
+export const roleSchema = z.enum(ROLES);
+const READER_SCOPES = ["chapters:read", "annotations:read"];
+const CONTRIBUTOR_SCOPES = [...READER_SCOPES, "annotations:write"];
+const EDITOR_SCOPES = [
+    ...CONTRIBUTOR_SCOPES,
+    "work:read",
+    "work:claim",
+    "submissions:write",
+];
+const MAINTAINER_SCOPES = [
+    ...EDITOR_SCOPES,
+    "tokens:manage",
+    "members:manage",
+];
+/** Role -> scope bundle (contract section 3). Bundles are cumulative. */
+export const ROLE_SCOPES = Object.freeze({
+    reader: READER_SCOPES,
+    contributor: CONTRIBUTOR_SCOPES,
+    editor: EDITOR_SCOPES,
+    maintainer: MAINTAINER_SCOPES,
+});
+/** The scope bundle a membership role grants (human sessions use this directly). */
+export function roleScopes(role) {
+    return ROLE_SCOPES[role];
+}
+/**
+ * An agent's effective scopes = token.scopes ∩ its membership role bundle
+ * (contract section 3). Result is deduplicated and in canonical SCOPES order.
+ */
+export function effectiveScopes(tokenScopes, role) {
+    const token = new Set(tokenScopes);
+    const bundle = new Set(ROLE_SCOPES[role]);
+    return SCOPES.filter((scope) => token.has(scope) && bundle.has(scope));
+}
+/** Require a single scope among the actor's effective scopes. */
+export function requireScope(actorScopes, required) {
+    if (actorScopes.includes(required)) {
+        return ALLOWED;
+    }
+    return denied("missing-scope", `actor lacks required scope "${required}"`);
+}
+/** Require every listed scope (denies on the first missing one, in SCOPES order). */
+export function requireScopes(actorScopes, required) {
+    const have = new Set(actorScopes);
+    for (const scope of SCOPES) {
+        if (required.includes(scope) && !have.has(scope)) {
+            return denied("missing-scope", `actor lacks required scope "${scope}"`);
+        }
+    }
+    return ALLOWED;
+}
+//# sourceMappingURL=scopes.js.map

package/dist/submission.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { type WorkItemType } from "@authorbot/schemas";
+import { type Decision } from "./decision.js";
+/**
+ * Submission command validation and the work-item-type -> submission-type
+ * capability mapping (Phase 4 contract section 4, design section 12.5).
+ * This module enforces shape, sizes, and cross-field rules only; Markdown
+ * prose safety on `content` (no raw HTML, allowed URL schemes) stays with
+ * `@authorbot/markdown` at the API layer, and lease-token verification is
+ * the API's constant-time hash compare.
+ */
+/** Phase 4 submission types (contract sections 1, 4). */
+export declare const SUBMISSION_TYPES: readonly ["range_replacement", "block_replacement", "chapter_replacement"];
+export declare const submissionTypeSchema: z.ZodEnum<{
+    range_replacement: "range_replacement";
+    block_replacement: "block_replacement";
+    chapter_replacement: "chapter_replacement";
+}>;
+export type SubmissionType = z.infer<typeof submissionTypeSchema>;
+/** Task-bundle `submissionSchema` id per type (design section 15.3). */
+export declare const SUBMISSION_SCHEMA_IDS: Readonly<Record<SubmissionType, string>>;
+/**
+ * Which submission type a work-item type requires (contract section 4:
+ * range -> range_replacement, block -> block_replacement, chapter ->
+ * chapter_replacement). `null` means the type is claimable but has no
+ * submission flow in Phase 4 (`write_chapter`/`planning`, contract
+ * section 1). Resolved ambiguity: `resolve_conflict` items carry both texts
+ * and are resolved by submitting the merged chapter, so they take
+ * `chapter_replacement`.
+ */
+export declare const WORK_ITEM_SUBMISSION_TYPES: Readonly<Record<WorkItemType, SubmissionType | null>>;
+/** The submission type a work-item type requires, or null when none exists yet. */
+export declare function requiredSubmissionType(type: WorkItemType): SubmissionType | null;
+export type SubmissionTypeDenialReason = "submission-type-mismatch" | "submission-not-supported";
+/**
+ * The "type matches work-item type" step of the contract section 4
+ * verification order. `write_chapter`/`planning` deny with
+ * `submission-not-supported` (deferred flow) so the API can surface an
+ * honest problem type instead of a generic mismatch.
+ */
+export declare function checkSubmissionTypeMatches(workItemType: WorkItemType, submissionType: SubmissionType): Decision<SubmissionTypeDenialReason>;
+/** Content cap (contract section 4): <= 512 KiB, measured in UTF-8 bytes. */
+export declare const MAX_SUBMISSION_CONTENT_BYTES: number;
+/** `sha256:` + 64 lowercase hex chars (task-bundle `contentHash` shape, section 15.3). */
+export declare const CONTENT_HASH_REGEX: RegExp;
+export declare const contentHashSchema: z.ZodString;
+/**
+ * `POST /work-items/{id}/submissions` (contract section 4): the HTTP body
+ * `{ leaseId, leaseToken, type, baseRevision, baseContentHash, content,
+ * summary?, notes? }` merged with the route's `workItemId`. The
+ * `Idempotency-Key` header, lease/holder/token verification, work-item
+ * state, and base-matches-bundle checks are separate ordered steps
+ * (`checkLeaseActive`, `transitionWorkItemPhase4`,
+ * `checkSubmissionTypeMatches`, `checkSubmissionBase`).
+ */
+export declare const submitWorkCommandSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        range_replacement: "range_replacement";
+        block_replacement: "block_replacement";
+        chapter_replacement: "chapter_replacement";
+    }>;
+    workItemId: z.ZodString;
+    leaseId: z.ZodString;
+    leaseToken: z.ZodString;
+    baseRevision: z.ZodNumber;
+    baseContentHash: z.ZodString;
+    content: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    summary: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    notes: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strict>;
+export type SubmitWorkCommand = z.infer<typeof submitWorkCommandSchema>;
+export type SubmissionBaseDenialReason = "base-revision-mismatch" | "base-hash-mismatch";
+/**
+ * The "baseRevision + baseContentHash match the lease's bundle" step
+ * (contract section 4). Revision is checked before hash so the commoner
+ * staleness cause surfaces first. Hash comparison here is not secret
+ * material (both values are content hashes the client already holds), so a
+ * plain compare is correct — constant-time treatment is for lease tokens.
+ */
+export declare function checkSubmissionBase(bundle: {
+    readonly baseRevision: number;
+    readonly baseContentHash: string;
+}, submission: {
+    readonly baseRevision: number;
+    readonly baseContentHash: string;
+}): Decision<SubmissionBaseDenialReason>;
+//# sourceMappingURL=submission.d.ts.map

package/dist/submission.js

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { uuidv7Schema } from "@authorbot/schemas";
+import { ALLOWED, denied } from "./decision.js";
+import { bodySchema, utf8ByteLength } from "./commands.js";
+import { leaseTokenSchema } from "./lease-token.js";
+/**
+ * Submission command validation and the work-item-type -> submission-type
+ * capability mapping (Phase 4 contract section 4, design section 12.5).
+ * This module enforces shape, sizes, and cross-field rules only; Markdown
+ * prose safety on `content` (no raw HTML, allowed URL schemes) stays with
+ * `@authorbot/markdown` at the API layer, and lease-token verification is
+ * the API's constant-time hash compare.
+ */
+/** Phase 4 submission types (contract sections 1, 4). */
+export const SUBMISSION_TYPES = [
+    "range_replacement",
+    "block_replacement",
+    "chapter_replacement",
+];
+export const submissionTypeSchema = z.enum(SUBMISSION_TYPES);
+/** Task-bundle `submissionSchema` id per type (design section 15.3). */
+export const SUBMISSION_SCHEMA_IDS = Object.freeze({
+    range_replacement: "authorbot.submission/range-replacement/v1",
+    block_replacement: "authorbot.submission/block-replacement/v1",
+    chapter_replacement: "authorbot.submission/chapter-replacement/v1",
+});
+/**
+ * Which submission type a work-item type requires (contract section 4:
+ * range -> range_replacement, block -> block_replacement, chapter ->
+ * chapter_replacement). `null` means the type is claimable but has no
+ * submission flow in Phase 4 (`write_chapter`/`planning`, contract
+ * section 1). Resolved ambiguity: `resolve_conflict` items carry both texts
+ * and are resolved by submitting the merged chapter, so they take
+ * `chapter_replacement`.
+ */
+export const WORK_ITEM_SUBMISSION_TYPES = Object.freeze({
+    revise_range: "range_replacement",
+    revise_block: "block_replacement",
+    revise_chapter: "chapter_replacement",
+    resolve_conflict: "chapter_replacement",
+    write_chapter: null,
+    planning: null,
+});
+/** The submission type a work-item type requires, or null when none exists yet. */
+export function requiredSubmissionType(type) {
+    return WORK_ITEM_SUBMISSION_TYPES[type];
+}
+/**
+ * The "type matches work-item type" step of the contract section 4
+ * verification order. `write_chapter`/`planning` deny with
+ * `submission-not-supported` (deferred flow) so the API can surface an
+ * honest problem type instead of a generic mismatch.
+ */
+export function checkSubmissionTypeMatches(workItemType, submissionType) {
+    const required = WORK_ITEM_SUBMISSION_TYPES[workItemType];
+    if (required === null) {
+        return denied("submission-not-supported", `work items of type "${workItemType}" have no submission flow in Phase 4`);
+    }
+    if (required !== submissionType) {
+        return denied("submission-type-mismatch", `work items of type "${workItemType}" require a "${required}" submission`);
+    }
+    return ALLOWED;
+}
+/** Content cap (contract section 4): <= 512 KiB, measured in UTF-8 bytes. */
+export const MAX_SUBMISSION_CONTENT_BYTES = 512 * 1024;
+/** `sha256:` + 64 lowercase hex chars (task-bundle `contentHash` shape, section 15.3). */
+export const CONTENT_HASH_REGEX = /^sha256:[0-9a-f]{64}$/;
+export const contentHashSchema = z
+    .string()
+    .regex(CONTENT_HASH_REGEX, "must be 'sha256:' followed by 64 lowercase hex characters");
+/**
+ * Replacement content: CRLF folded to LF (matching chapter storage) but NOT
+ * trimmed — leading/trailing whitespace is meaningful in a range
+ * replacement. Emptiness is a per-type rule handled in the command schema:
+ * an empty `range_replacement` is a deletion and legal; block and chapter
+ * replacements must be non-empty.
+ */
+const submissionContentSchema = z
+    .string()
+    .transform((value) => value.replace(/\r\n/g, "\n"))
+    .refine((value) => utf8ByteLength(value) <= MAX_SUBMISSION_CONTENT_BYTES, `content must be at most ${MAX_SUBMISSION_CONTENT_BYTES} bytes of UTF-8`);
+const submitWorkBase = {
+    workItemId: uuidv7Schema,
+    leaseId: uuidv7Schema,
+    leaseToken: leaseTokenSchema,
+    baseRevision: z.number().int().min(1),
+    baseContentHash: contentHashSchema,
+    content: submissionContentSchema,
+    /**
+     * `summary`/`notes` are unpinned by the contract; this package reuses the
+     * annotation body rule (normalized, non-empty, <= 32 KiB UTF-8).
+     */
+    summary: bodySchema.optional(),
+    notes: bodySchema.optional(),
+};
+/**
+ * `POST /work-items/{id}/submissions` (contract section 4): the HTTP body
+ * `{ leaseId, leaseToken, type, baseRevision, baseContentHash, content,
+ * summary?, notes? }` merged with the route's `workItemId`. The
+ * `Idempotency-Key` header, lease/holder/token verification, work-item
+ * state, and base-matches-bundle checks are separate ordered steps
+ * (`checkLeaseActive`, `transitionWorkItemPhase4`,
+ * `checkSubmissionTypeMatches`, `checkSubmissionBase`).
+ */
+export const submitWorkCommandSchema = z
+    .strictObject({ ...submitWorkBase, type: submissionTypeSchema })
+    .superRefine((command, ctx) => {
+    if (command.type !== "range_replacement" && command.content.length === 0) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["content"],
+            message: `content must not be empty for a ${command.type}`,
+        });
+    }
+});
+/**
+ * The "baseRevision + baseContentHash match the lease's bundle" step
+ * (contract section 4). Revision is checked before hash so the commoner
+ * staleness cause surfaces first. Hash comparison here is not secret
+ * material (both values are content hashes the client already holds), so a
+ * plain compare is correct — constant-time treatment is for lease tokens.
+ */
+export function checkSubmissionBase(bundle, submission) {
+    if (submission.baseRevision !== bundle.baseRevision) {
+        return denied("base-revision-mismatch", `submission is against revision ${submission.baseRevision} but the lease was issued for revision ${bundle.baseRevision}`);
+    }
+    if (submission.baseContentHash !== bundle.baseContentHash) {
+        return denied("base-hash-mismatch", "submission base content hash does not match the lease's task bundle");
+    }
+    return ALLOWED;
+}
+//# sourceMappingURL=submission.js.map

package/dist/token.d.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { type Decision } from "./decision.js";
+/**
+ * Token and session VALUE rules only (Phase 2 contract section 3). This
+ * module is deliberately crypto-free: generating randomness and hashing
+ * (SHA-256, HMAC) are the API layer's job. Nothing here ever logs or embeds
+ * a full credential in an error message.
+ */
+/** Agent token: `authorbot_` + 43 base64url chars (256-bit random). */
+export declare const AGENT_TOKEN_PREFIX = "authorbot_";
+export declare const AGENT_TOKEN_SECRET_LENGTH = 43;
+export declare const AGENT_TOKEN_REGEX: RegExp;
+export declare const agentTokenSchema: z.ZodString;
+export declare function isAgentTokenFormat(value: string): boolean;
+export type AgentTokenParseFailure = "bad-prefix" | "bad-length" | "bad-charset";
+export type AgentTokenParseResult = {
+    readonly ok: true;
+    readonly secret: string;
+} | {
+    readonly ok: false;
+    readonly reason: AgentTokenParseFailure;
+};
+/**
+ * Shape-check a presented credential and split off the secret part (which the
+ * API layer hashes for lookup). Failure results carry a reason only — never
+ * any fragment of the presented value.
+ */
+export declare function parseAgentToken(value: string): AgentTokenParseResult;
+/**
+ * Human session id: opaque 256-bit value (contract section 3). The contract
+ * does not pin an encoding; this package pins base64url (43 chars), matching
+ * the agent-token secret encoding, and the API must generate accordingly.
+ * Cookie signing (HMAC) is out of scope here.
+ */
+export declare const SESSION_ID_LENGTH = 43;
+export declare const SESSION_ID_REGEX: RegExp;
+export declare const sessionIdSchema: z.ZodString;
+export declare function isSessionIdFormat(value: string): boolean;
+/** Agent-token TTL bounds (contract section 3: <= 90d, default 30d). */
+export declare const MAX_TOKEN_TTL_DAYS = 90;
+export declare const DEFAULT_TOKEN_TTL_DAYS = 30;
+/** Human session TTL (contract section 3: 7d). */
+export declare const SESSION_TTL_DAYS = 7;
+/** Format a Date as the contract's RFC 3339 UTC second-precision timestamp. */
+export declare function toTimestamp(date: Date): string;
+export type TokenExpiryResult = {
+    readonly ok: true;
+    readonly expiresAt: string;
+} | {
+    readonly ok: false;
+    readonly reason: "ttl-out-of-range";
+};
+/**
+ * Resolve an agent token's `expires_at` from mint time and requested TTL.
+ * Missing TTL means the 30-day default; anything outside 1..90 whole days is
+ * rejected rather than clamped.
+ */
+export declare function resolveTokenExpiry(now: Date, requestedDays?: number): TokenExpiryResult;
+/** Resolve a human session's `expires_at` (7 days from issue). */
+export declare function resolveSessionExpiry(now: Date): string;
+export type TokenInactiveReason = "revoked" | "expired";
+/**
+ * Whether a stored token row is still usable at `now`. Revocation wins over
+ * expiry; expiry is inclusive (a token is expired at exactly `expires_at`).
+ */
+export declare function checkTokenActive(token: {
+    expiresAt: string;
+    revokedAt?: string | null;
+}, now: Date): Decision<TokenInactiveReason>;
+/** `last_used_at` update throttle (contract section 3: at most once per minute). */
+export declare const LAST_USED_UPDATE_INTERVAL_MS = 60000;
+export declare function shouldUpdateLastUsed(lastUsedAt: string | null | undefined, now: Date): boolean;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { ALLOWED, denied } from "./decision.js";
+/**
+ * Token and session VALUE rules only (Phase 2 contract section 3). This
+ * module is deliberately crypto-free: generating randomness and hashing
+ * (SHA-256, HMAC) are the API layer's job. Nothing here ever logs or embeds
+ * a full credential in an error message.
+ */
+/** Agent token: `authorbot_` + 43 base64url chars (256-bit random). */
+export const AGENT_TOKEN_PREFIX = "authorbot_";
+export const AGENT_TOKEN_SECRET_LENGTH = 43;
+const BASE64URL_CHAR = /^[A-Za-z0-9_-]+$/;
+export const AGENT_TOKEN_REGEX = /^authorbot_[A-Za-z0-9_-]{43}$/;
+export const agentTokenSchema = z
+    .string()
+    .regex(AGENT_TOKEN_REGEX, "must be 'authorbot_' followed by 43 base64url characters");
+export function isAgentTokenFormat(value) {
+    return AGENT_TOKEN_REGEX.test(value);
+}
+/**
+ * Shape-check a presented credential and split off the secret part (which the
+ * API layer hashes for lookup). Failure results carry a reason only — never
+ * any fragment of the presented value.
+ */
+export function parseAgentToken(value) {
+    if (!value.startsWith(AGENT_TOKEN_PREFIX)) {
+        return { ok: false, reason: "bad-prefix" };
+    }
+    const secret = value.slice(AGENT_TOKEN_PREFIX.length);
+    if (secret.length !== AGENT_TOKEN_SECRET_LENGTH) {
+        return { ok: false, reason: "bad-length" };
+    }
+    if (!BASE64URL_CHAR.test(secret)) {
+        return { ok: false, reason: "bad-charset" };
+    }
+    return { ok: true, secret };
+}
+/**
+ * Human session id: opaque 256-bit value (contract section 3). The contract
+ * does not pin an encoding; this package pins base64url (43 chars), matching
+ * the agent-token secret encoding, and the API must generate accordingly.
+ * Cookie signing (HMAC) is out of scope here.
+ */
+export const SESSION_ID_LENGTH = 43;
+export const SESSION_ID_REGEX = /^[A-Za-z0-9_-]{43}$/;
+export const sessionIdSchema = z
+    .string()
+    .regex(SESSION_ID_REGEX, "must be 43 base64url characters (256-bit)");
+export function isSessionIdFormat(value) {
+    return SESSION_ID_REGEX.test(value);
+}
+/** Agent-token TTL bounds (contract section 3: <= 90d, default 30d). */
+export const MAX_TOKEN_TTL_DAYS = 90;
+export const DEFAULT_TOKEN_TTL_DAYS = 30;
+/** Human session TTL (contract section 3: 7d). */
+export const SESSION_TTL_DAYS = 7;
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+/** Format a Date as the contract's RFC 3339 UTC second-precision timestamp. */
+export function toTimestamp(date) {
+    if (Number.isNaN(date.getTime())) {
+        throw new RangeError("invalid Date");
+    }
+    return `${date.toISOString().slice(0, 19)}Z`;
+}
+/**
+ * Resolve an agent token's `expires_at` from mint time and requested TTL.
+ * Missing TTL means the 30-day default; anything outside 1..90 whole days is
+ * rejected rather than clamped.
+ */
+export function resolveTokenExpiry(now, requestedDays) {
+    const days = requestedDays ?? DEFAULT_TOKEN_TTL_DAYS;
+    if (!Number.isInteger(days) || days < 1 || days > MAX_TOKEN_TTL_DAYS) {
+        return { ok: false, reason: "ttl-out-of-range" };
+    }
+    return { ok: true, expiresAt: toTimestamp(new Date(now.getTime() + days * MS_PER_DAY)) };
+}
+/** Resolve a human session's `expires_at` (7 days from issue). */
+export function resolveSessionExpiry(now) {
+    return toTimestamp(new Date(now.getTime() + SESSION_TTL_DAYS * MS_PER_DAY));
+}
+/**
+ * Whether a stored token row is still usable at `now`. Revocation wins over
+ * expiry; expiry is inclusive (a token is expired at exactly `expires_at`).
+ */
+export function checkTokenActive(token, now) {
+    if (token.revokedAt !== undefined && token.revokedAt !== null) {
+        return denied("revoked", "token has been revoked");
+    }
+    if (now.getTime() >= Date.parse(token.expiresAt)) {
+        return denied("expired", "token has expired");
+    }
+    return ALLOWED;
+}
+/** `last_used_at` update throttle (contract section 3: at most once per minute). */
+export const LAST_USED_UPDATE_INTERVAL_MS = 60_000;
+export function shouldUpdateLastUsed(lastUsedAt, now) {
+    if (lastUsedAt === undefined || lastUsedAt === null) {
+        return true;
+    }
+    return now.getTime() - Date.parse(lastUsedAt) >= LAST_USED_UPDATE_INTERVAL_MS;
+}
+//# sourceMappingURL=token.js.map

package/dist/vote.d.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { type AnnotationKind } from "@authorbot/schemas";
+import { type Decision } from "./decision.js";
+/**
+ * Vote commands (Phase 3 contract section 2):
+ * `PUT /v1/projects/{p}/annotations/{id}/vote` with `{ value }`, `DELETE`
+ * clears. One current vote per actor is a DB uniqueness concern (upsert);
+ * this module pins the command shapes and the suggestion-only rule.
+ */
+/** Vote values (contract section 2; mirrors `authorbot.instance/v1` `votes.values`). */
+export declare const VOTE_VALUES: readonly ["approve", "reject", "abstain"];
+export declare const voteValueSchema: z.ZodEnum<{
+    approve: "approve";
+    reject: "reject";
+    abstain: "abstain";
+}>;
+export type VoteValue = z.infer<typeof voteValueSchema>;
+/** `PUT .../annotations/{annotationId}/vote` — route param + body merged. */
+export declare const castVoteCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+    value: z.ZodEnum<{
+        approve: "approve";
+        reject: "reject";
+        abstain: "abstain";
+    }>;
+}, z.core.$strict>;
+export type CastVoteCommand = z.infer<typeof castVoteCommandSchema>;
+/** `DELETE .../annotations/{annotationId}/vote` — the command is the route param. */
+export declare const clearVoteCommandSchema: z.ZodObject<{
+    annotationId: z.ZodString;
+}, z.core.$strict>;
+export type ClearVoteCommand = z.infer<typeof clearVoteCommandSchema>;
+export type VoteDenialReason = "not-a-suggestion";
+/**
+ * Suggestion-only guard (contract section 2: votes on comments → 422). Votes
+ * stay legal after `open` — sticky decisions require tracking vote changes on
+ * `work_item_created` annotations (contract section 4) — so annotation status
+ * is deliberately not checked here; `votes:write` scope enforcement is the
+ * API layer's (`requireScope`).
+ */
+export declare function authorizeVote(input: {
+    annotationKind: AnnotationKind;
+}): Decision<VoteDenialReason>;
+//# sourceMappingURL=vote.d.ts.map