@starkeep/admin-manifest

Zod schema, types, and validator for Starkeep app manifests.

An app manifest is the single declaration a Starkeep app (built-in or installable) makes about itself: identity, install targets, requested file-extension grants, IAM-shaped permissions, app-specific syncable state, and any compute / shared-resource infra it needs. The admin-installer reads it to plan installs; admin-web reads it to render the Apps page and to spawn local dev processes.

This package is the source of truth for that schema. It only describes and validates manifests — it does not load, persist, or apply them.

Exports

import {
  appManifestSchema,
  validateManifest,
  KNOWN_EXTENSIONS,
  type AppManifest,
  type ValidationResult,
} from "@starkeep/admin-manifest";

• appManifestSchema — the top-level Zod schema. Defaults are applied on parse (e.g. targets defaults to ["local"], infraRequirements to an empty requirements block).
• Per-section schemas + inferred types: fileAccessSchema / FileAccess, infraRequirementsSchema / InfraRequirements, appComputeHandlerSchema / AppComputeHandler, syncableTableSchema / SyncableTable, appSpecificSyncableSchema / AppSpecificSyncable, permissionEntrySchema / PermissionEntry, localRunSchema / LocalRun, sharedResourceRequirementSchema / SharedResourceRequirement, appTierSchema / AppTier.
• validateManifest(raw) => ValidationResult — parses with the schema and then applies cross-field rules that Zod alone cannot express.
• KNOWN_EXTENSIONS — re-exported from @starkeep/protocol-primitives; the set of file extensions an installable app is allowed to claim.

validateManifest

interface ValidationResult {
  valid: boolean;
  manifest: AppManifest | null;   // populated only when valid
  errors: string[];
  warnings: string[];
  impliedCategories: string[];    // distinct categories implied by fileAccess extensions
}

In addition to schema parsing, the validator enforces:

• Community-tier apps may not use the reserved @starkeep/ id prefix.
• Every extension in infraRequirements.fileAccess[].extensions must be in KNOWN_EXTENSIONS. Apps cannot register new types — adding one requires editing @starkeep/protocol-primitives's core-types.ts.
• infraRequirements.fileAccessAll is reserved for starkeep-drive (the User-Data-Owner). All other apps must enumerate extensions.
• infraRequirements.brokerPower is reserved for cloud-data-server.
• compute.enabled requires at least one handler.
• Warns when metadataWrite is set alongside access: "readwrite" (redundant).

Manifest shape (quick reference)

• id, name, version, tier (official | verified | community)
• targets: where the app can be installed — local, cloud, or both. Drives the Apps page's Local / Cloud split.
• requiredPermissions, optionalPermissions: IAM-shaped entries against shared-data resources (type / collection / wildcard) with read / write / delete / admin.
• infraRequirements:
  • fileAccess[]: enumerated extension grants with rationale and optional metadataWrite.
  • fileAccessAll: Drive-only all-access.
  • compute: enable + Lambda handler definitions (runtime, memory, timeout, routes, env, auth). handler resolves inside the app's bundled dist.zip; the installer does not synthesize handler code.
  • appSpecificSyncable: private per-app syncable tables (mapped to <appId>_syncable_<name> in local SQLite) and optional files opt-in for the apps/<appId>/syncable/ object-storage prefix. updated_at and deleted_at are reserved column names.
  • additionalResources / sharedResources: extra cloud resources (cloudfront, custom).
  • brokerPower: cloud-data-server only.
• localRun: how admin-web should spawn the app's local process. With portFlag set, admin-web allocates a free port and appends [portFlag, <port>] to args.

Scripts

• pnpm build — bundle with tsup
• pnpm test — vitest
• pnpm typecheck — tsc --noEmit
• pnpm lint — eslint