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
-
appis the app's name: 2 to 63 lowercase letters, digits and dashes, starting with a letter and not ending with a dash (E-MAN-004). It gives the app its address inaicoded dev, and other apps,dev.yamland theaicoded mcptools name the app by it. -
classnames the app type the app belongs to, which security defines: lower-case letters, digits and dashes, starting with a letter, such asinternal-tool(E-MAN-015). Left out, the app is an Internal tool,internal-tool; see app types. -
owneris the group of the company that owns the app,group:<name>, such asgroup:hr-leads. A group's name is lower-case letters, digits, dots, dashes and underscores, starting and ending with a letter or digit (E-MAN-016). -
audiencesays who may use the app, each entry once (E-MAN-017):internallists people of the company:group:<name>for a group, oreveryone;externallists outside people:idp:<name>for the users of a partner's identity provider, with a lower-case name, ormagic-linkfor known outside users who sign in with a link sent to their email.
An audience that lists no one is Not allowed (E-MAN-024): every app is used by people who sign in.
aicoded initstarts withinternal: [everyone]. On the platform, each group is a name of the organisation's group map (E-REL-020). -
datalists the sources of data the app reaches, each with theclassesof data it holds: at least one ofpublic,internal,confidentialandpersonal, from the least sensitive to the most (E-MAN-008). The app type sets the highest class its apps may hold. Health, HR and payment card data, the classeshealth,hrandcard, are Not allowed in any app (E-MAN-024).sqldbis the app's own SQL database; see the SQL database.filestore:<name>is one of its file stores; see file stores.connector:<name>names a company system the app reads with each viewer's own access. No building block reads one yet.
Names are lower-case letters, digits and dashes, and each source is listed once (E-MAN-007).
-
egresslists the outside services the app calls over HTTPS on port 443. An entry is a host alone, or a host with a key that the runner adds to every request to it:egress: - hooks.partner.example # a host alone - host: api.partner.example # a host with a key secret: partner_api_key # a secret declared in secrets header: Authorization # the header the key goes in prefix: "Bearer " # text before the key, if the service wants oneA host is a lower-case name such as
api.partner.example, with no scheme, port, path, wildcard or IP address, none whose last label islocalhost,local,internalorarpa, and none of the platform's own, such asaicoded.cloud,aicoded.devand their subdomains. Each host is listed once, alone or with a key (E-MAN-018). A key'ssecretis declared insecrets; itsheaderis a header name of at most 64 characters, and notHost,Content-Length,Content-Type,Cookieor a header of the connection itself, such asConnectionorTransfer-Encoding; itsprefix, which may be left out, is at most 64 printable ASCII characters (E-MAN-025). One secret may go to several hosts. The app never reads a key it binds: it calls the service withoutbound.Client(), and the runner adds the key. See outside services. -
emailhasfrom, one plain lower-case address, andto_domains, the lower-case domains the app may send to, with no wildcards and no non-ASCII names (E-MAN-009). See mail. -
schedulelists the app's scheduled jobs, each as{cron: "<expression>", job: <name>}(E-MAN-019).jobis a lower-case name of letters, digits and dashes, each job once.cronis five fields in UTC separated by spaces: minute (0-59), hour (0-23), day of the month (1-31), month (1-12) and weekday (0-6, with 0 for Sunday). A field is*, a number, a rangea-b, a step*/nora-b/n, or a comma list of them; names such asMON,?,L,W,#and@dailyare not accepted. No building block runs a job yet. -
settingsandsecretsname the values the app reads: lowercase letters, digits and_, starting with a letter, each once (E-MAN-005). Their values are not in the file: on your computer they come fromdev.yaml, and on the platform they are set in the console. See settings and secrets. -
moduleslists the third-party Go modules the app's code uses, by module path, such asgolang.org/x/text: each once, without a version, which comes fromgo.mod(E-MAN-013).aicoded checkrefuses a third-party module that the app, or a module it lists, imports without an entry (E-LINT-002), and checks the code of every module listed: it may not run programs, open network connections, make system calls, useunsafe,//go:linknameor assembly, call methods throughreflect, import the framework, open a database, run SQL, replace the default logger or change a variable of the standard library or the framework (E-LINT-003). The framework and the modules only it imports need no entry, nor does a module only tests use. -
sizeis the app's size limit,S,MorL(E-MAN-020), andresourcesits runtime limit,small,mediumorlarge(E-MAN-021). -
ttlis how long the app may live before it is reviewed: a number of days from 1 to 3650 followed byd, such as180d(E-MAN-022).
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"]
requirelists the access rules on the page's path that do not admit every viewer, root first, with the roles of one rule joined by|;["*"]means every viewer the company login lets in.guard: truesays that aGuardon the page's path runs for it.shared: truesays that everyone the rules admit may see every record of a page with an id in its URL: the nearest template, from the page up to its deepest parameter folder, that says whose records the page shows declaresshared="true". A page with an id in its URL hasguard: trueorshared: true, never both (E-MAN-023); see access.callsnames the page calls of the page and of the layouts it is shown in.
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
data,egress,email,settings,secrets,modules,accessandservicesare enforced as above, by the runner,aicoded checkand the delivery pipeline.class,audience,data,email.to_domainsand the hosts ofegressare compared with the app type when a publish passes, and decide whether its release is Pre-approved or Needs approval; see app types. A key that is new, or that goes to a host in another way than in the app's live release, always Needs approval: the approver sees which key goes to which outside service. The runner lets in only the peopleaudiencenames, through the organisation's group map.- The platform records the other fields,
owner,schedule,size,resourcesandttl, and shows each change to the permission list in the app's change record. Holding the app to them comes later, with limits. Until the platform runs schedules, a release to production refuses a permission list withschedulejobs, and one withegressthat was built with a framework older than v0.10.0 (E-REL-017); until outside people can sign in, one withaudience.external(E-REL-004).
See also
- Access: the rules the
accesssection records. - Calls between apps: the
servicessection. - App types: what the app type allows, and what needs approval.
- Publishing: the change record of each publish.
- people/aicoded.yaml, contacts/aicoded.yaml and room-maintenance/aicoded.yaml: the permission lists of the examples.