append adds an event to the ring buffer, evicting the oldest if full.

appendToCatalog inserts def into Catalog. Called from catalog_<resource>.go init() functions. Keep this small + simple; validation happens at Register

configureBootstrapToken seeds a known token on the server so tests don't depend on the random generator. The on-disk file is created in a temp dir so

connectSSE connects to the SSE endpoint on a real test server and returns a channel of parsed events. Cancel the context to disconnect.

createBulkTestItem creates a task and returns it.

createTestWorkspace creates a workspace via API and returns its slug.

decrypt decrypts a value that was encrypted with encrypt(). If the value doesn't have the "enc:" prefix, it's treated as plaintext (backward compatibi

doArtifactRequest posts a raw (non-JSON) body to an artifact-import endpoint.

filterAttention returns attention items of a given type.

helper: fetch the workspace graph and return the parsed response

mapItemCreate translates an `item create` MCP call into a POST to api/v1/workspaces/{ws}/collections/{coll}/items. The MCP tool schema (auto-generate

BackfillOAuthConnections tests (PLAN-1519 / TASK-1522 / IDEA-1517 §2). What's covered: - Pre-TASK-952 session (no key) → all_current=1, no

OAuth connection store tests (PLAN-1519 / TASK-1520 — Phase A foundation). What's covered: - CreateOAuthConnection + GetOAuthConnection round-trip w

newPadServer stands up the same *server.Server that production uses, wired to a fast fixture SQLite store (storetest.NewSQLite, IDEA-1914). Mirrors te

newTestRequest builds an OAuthRequest with sensible defaults; tests override fields they care about. signature uniqueness is the caller's responsibili

renderMD is a small test helper that builds + renders the synthetic tree with a fixed clock and returns the markdown output as a string.

runOrphanGCSweep walks the orphaned-attachments query and reclaims rows past the grace period. Two reclamation paths: - DB row only. content_hash is

slugify converts a string to a URL-friendly slug.

uploadHelper does a fresh upload and returns the parsed response.

waitForEvent reads from the event channel with a timeout.

withTempHome chroots ~/.pad to a fresh tempdir for the test. CredentialsPath resolves via os.UserHomeDir → $HOME, so a t.Setenv("HOME", ...) is enough

writeItemResolveError distinguishes a soft-deleted (archived) item from a genuinely-missing one for mutation handlers. An archived item still appears

CreateComment adds a new comment to an item. userID is the authenticated user authoring the comment (empty for agent/system comments); it's stored as

--- Invitations --- CreateInvitation creates a pending workspace invitation. Generates a 128-bit (16-byte) random code and stores only its SHA-256 has

EnsureEncryptionKey makes sure the server has a usable encryption key without requiring the operator to set one explicitly. Resolution order: 1. If c

EventsSince returns events for a workspace with IDs greater than sinceID. Used to replay missed events on SSE reconnect (Last-Event-ID). Returns nil i

FormatForTool takes the raw embedded skill content and formats it for a specific tool. Returns the appropriately formatted content with tool-specific

IsCloud reports whether the server is running in cloud mode.

MoveItem moves an item to a different collection within the same workspace. It updates the collection_id and fields JSON. The item_number is preserved

ParseTrustedProxyCIDRs parses a comma-separated list of CIDRs or bare IPs from the PAD_TRUSTED_PROXIES setting. Bare IPs get /32 (IPv4) or 128 (IPv6).

RestoreBoundary returns the restore boundary recorded for itemID, or (0, false) when none has been set. The collab-snapshot PATCH handler consults it

Send sends an email using the default from address/name.

SetBypassSetupToken wires the operator's PAD_BYPASS_SETUP_TOKEN choice into the Server. When true, handleBootstrap accepts a self-host first-admin POS

SetIPChangeEnforce controls how the auth middleware reacts when a session's binding (client IP OR User-Agent hash) changes mid-lifetime: - mode == "st

MCP transport state. Set at startup by cmd/pad/main.go via SetMCPTransport when the deployment is in cloud mode (PAD_MODE=cloud). Self-hosted deployme

TerminalValuesForDoneField returns the resolved done-field key and the list of terminal values for that field. If the resolved field has no terminal_o

ValidateExamples is the contractual mechanism by which cmdhelp v0.1 prevents documentation drift (spec §6, §11 Q5). For every example in every command

--- TOML config path (Codex) -------------------------------------------- Codex nests its MCP servers in a TOML `[mcp_servers.pad]` table, so the JSO

audienceMatchingStrategy returns a fosite.AudienceMatchingStrategy that enforces "every requested audience must equal the configured canonical audienc

createTaskWithFields is a small helper for the field-patch/OCC tests: POST a task with the given fields JSON and return the created item.

csrfCookieName returns the CSRF cookie name. Uses the same __Host- prefix strategy as the session cookie.

doJSONReq drives a JSON request through srv and returns the recorder. Mirrors the local pattern in internal/server/server_test.go::doRequest, kept pac

doRequestWithHeadersFromAddr lets us combine arbitrary headers with a non-loopback remote-addr. Existing helpers cover one or the other but not both.

docWith constructs a minimal Document with two commands sharing a `collection` arg (caching test) and one `role` flag.

fakeSessionServer returns an httptest.Server whose /api/v1/auth/session handler responds with the SessionResponse produced by `gen` (called once per r

mapCollectionUpdate dispatches `pad collection update <slug> [--name ...] [--icon ...] [--description ...] [--prefix ...] [--schema ...] [--fields ...

newMCPSessionTracker constructs a tracker with the given TTL and optional onChange callback. ttl <= 0 falls back to the default; onChange may be nil (

newStub starts a test HTTP server and returns a CloudClient pointed at it. Callers supply the handler to control the response.

readBinaryWithin reads a single binary frame within d. Returns the payload bytes or fails the test on timeout.

readControlWithin reads frames off the conn within d, drains payload (binary) frames, and returns the FIRST TextMessage parsed as a ControlMessage. Te

seedBackfillClient mirrors seedClient in connected_apps_test.go but stays internal to this file so the backfill suite can run in isolation when other

seedConnectedAppForMutations creates a user + workspace + an oauth_connections row directly so the mutation handlers have something to mutate. Returns

Phase 2 permission test suite (TASK-488). Tests collection-level visibility, system collection exemptions, and the VisibleCollectionIDs resolution log

* Read a string param. Absent (undefined/null) returns undefined — not an * error, matching strArray's absent-vs-malformed line. A present value of a

validatePasswordStrength enforces length + strength. It rejects weak passwords at registration / rotation / reset so top-of-breach-list entries like "

workspaceRole returns the user's role in the current workspace, as set by RequireWorkspaceAccess. Returns empty string if not set.

AllowedWorkspaces returns the workspace allow-list stored in session.Extra at consent time (TASK-952). Three return shapes matter to callers: - nil —

============================================================ Refresh tokens (handler/oauth2/storage.go RefreshTokenStorage) ==========================

DoneFieldKey resolves which field on a collection's schema represents "is this item done?". The resolution is: 1. If CollectionSettings.BoardGroupBy

EncryptionKeyFile returns the on-disk path where an auto-generated encryption key is persisted. Operator-provided keys (PAD_ENCRYPTION_KEY env, encryp

Fetch performs a GET against rawURL, re-validating every redirect hop and aborting if the response exceeds the size cap. Returns a wrapped error suita

GetComment returns a single comment by ID.

GetParentForItem returns the parent link for an item, or nil if it has no parent. A parent link pointing to a soft-deleted item is treated as no paren

Install adds (or refreshes) the pad entry in the named agent's config. Returns the resolved path + whether the file was actually modified (false on a

MigrateFields maps field values from a source schema to a target schema. Fields with matching keys and compatible types are transferred. Incompatible

NewRegistry returns an empty registry.

NewServer constructs an OAuth 2.1 authorization server backed by fosite v0.49.0. Compliance posture (PLAN-943 TASK-951): - PKCE required (S256 only)

ResolveAttachmentReferences scans `markdown` for `pad-attachment:UUID` references in standard markdown image/link syntax and replaces each with render

RoomCount is a test/debug accessor. Production code shouldn't make decisions based on this — the count is racy with grace-timer expirations.

SubscriberCount returns the number of active subscribers for the given item. Useful for room-manager TTL accounting (TASK-1255 — when the count hits 0

TrustedProxyRealIP returns middleware that rewrites r.RemoteAddr from X-Real-IP / X-Forwarded-For ONLY when the direct TCP peer is within one of the s

applySQLiteMigration applies a single migration file atomically. Behavior (IDEA-1485): 1. PRAGMA statements are lifted out of the migration body (se

assertBlocked asserts the response is a 403 email_not_verified.

auditUser creates a user that subsequent audit rows can FK-reference. The schema requires user_id REFERENCES users(id), so we can't insert audit rows

buildFositeRequest produces a fully-populated *fosite.Request so adapter tests can drive Create*Session methods without depending on fosite's HTTP ent

buildHTMLShell wraps body HTML in the standard transactional-email chrome — header (Pad wordmark) + body + footer note + (Cloud only) marketing footer

dialWSBracket joins as a bracket-capable participant (`?applier_bracket=1`) so the conn can be durably confirmed by a restore's finalization (BUG-2276

doRequestWithCookieFrom is like doRequestWithCookie but lets the caller set the request RemoteAddr so tests can simulate a session jumping to a differ

expandPath substitutes {key} placeholders in template using input. Each placeholder must appear as a non-empty string in input; otherwise expandPath r

getOrCreate returns the existing Room for itemID or, atomically under m.mu, mints a new one. Holding m.mu across the lookup + insertion keeps the grac

isItemVisibleToGuest checks if an item is visible given grant-based access, considering both full-collection grants and individual item grants. When f

logActivity is a helper that logs activity, ignoring errors (best-effort).

mapCollectionCreate dispatches `pad collection create <name> [--fields key:type[:opts]; ...] [--icon ...] [--description ...] [--layout ...] [--defaul

maybeInjectWorkspace defaults the `workspace` input from the dispatcher's WorkspaceLister when the caller didn't pass one explicitly (TASK-1076). The

Store-layer tests for the MCP audit log (PLAN-943 TASK-960). What's covered: - InsertMCPAuditEntry validates required fields and round-trips correct