aicoded.dev

The permission list: aicoded.yaml

aicoded.yaml declares who owns and uses the app and everything it reaches: its data, the outside services it calls, the address it mails from and the domains it mails to, its scheduled jobs, its settings and secrets, who may open each page, and the functions it calls and serves. Security reads it instead of the code, and the app itself never holds a password or a key.

An example

# aicoded.yaml
app: room-maintenance
class: internal-tool               # the app type, given by security
owner: group:hotel-ops-leads       # the group that owns the app
audience:
  internal: [group:hotel-staff]    # people of the company who use it
  external: []                     # outside people, such as [idp:partners, magic-link]
data:
  - source: sqldb                  # the app's own SQL database
    classes: [internal]
  - source: filestore:photos       # the app's file store named photos
    classes: [internal]
egress: [api.partner.example]      # outside services it calls, over HTTPS
email:
  from: rooms@acme.example         # the one address the app sends from
  to_domains: [acme.example]       # the only domains it may send to
schedule:
  - {cron: "0 6 * * *", job: daily-summary}   # 06:00 UTC every day
settings: [report_day]             # read with config.String
secrets: [partner_api_key]         # read with secrets.Get
modules: [golang.org/x/text]       # third-party modules the code uses
size: S                            # the size limit, given by the budget owner
resources: small                   # the runtime limit, given by the budget owner
ttl: 180d                          # days until the app is reviewed
# access is written by aicoded generate from <ssr:access>; do not edit it
access:
  "/rooms":
    require: ["hotel-staff"]
# services is written by aicoded generate from rpc/ and the clients in services/; do not edit it
services:
  calls:
    "inventory": ["ReserveParts"]

You or your AI assistant write every section but access and services, which aicoded generate adds and keeps current. app and audience are required; any other section left out, or left empty, is not stated.

The sections you write

An AI assistant writes owner and audience when the person says who owns and uses the app. It leaves class, size, resources and ttl out unless the person or their administrator gives them: security and the budget owner set them.

An unknown key is an error (E-MAN-014): at the top level, in audience, in each entry of data, egress and schedule, in email, and in access and services, so that a misspelt key never goes unseen. The file may not use an anchor, an alias or a merge key, &name, *name or <<: write every value out in full (E-MAN-003). aicoded check reports every problem of the file at once, in line order.

The sections aicoded generate writes

aicoded generate, which aicoded dev and aicoded check run first, writes the access section from the pages' <ssr:access>: one entry per page a viewer can open, keyed by its URL pattern. A layout with pages below it has no entry of its own.

# access is written by aicoded generate from <ssr:access>; do not edit it
access:
  "/users/add":
    require: ["staff", "hr"]
  "/users/{login}/contacts":
    require: ["staff"]
    guard: true
  "/users/{login}/info":
    require: ["staff"]
    shared: true
  "/notes/{id}":
    require: ["*"]
    guard: true
    calls: ["star"]

It writes the services section from rpc/ and the clients in services/: the functions the app calls and the ones it serves; see calls between apps. An app with no pages gets access: {}.

Never edit either section: aicoded generate rewrites them from the code and leaves the rest of the file as it was. It refuses a file whose sections it cannot replace without touching the rest: keep aicoded.yaml one YAML document in block style, with every top-level key at the start of a line and one access and one services section (E-MAN-003).

How the app is held to it

The runner gives the app only what the permission list declares, and the framework names the section to add when the app reaches for more:

The app Without Fails with
opens its database with sqldb.Open - source: sqldb E-MAN-010
opens a store with filestore.Open(ctx, "photos") - source: filestore:photos E-MAN-011
sends or reads mail an email section E-MAN-012
mails a domain the domain in to_domains E-MAIL-003
reads a setting with config.String its name in settings E-MAN-001
reads a secret with secrets.Get its name in secrets E-MAN-002
calls a function of another app the call in services.calls E-RPC-008
calls an outside service with outbound.Client() its host in egress E-OUT-001

Every page needs an access rule on its path, so every page is in access. Together the sections say, in a form security can read, who uses the app, what data it reaches and where its mail goes, without reading its code.

What the platform does with it

See also

Markdown · Source on GitHub · framework f46741f