Permissions

This page lists every permission setting in alien.ts: the profiles your workloads run as, Alien's management access, and every built-in permission set. The management identity is the scoped cloud identity the customer's admin creates at initial setup, their one-time step, so Alien can update the deployment afterwards.

Nothing is granted unless you declare it, and each grant becomes a native cloud policy the customer can review.

import * as alien from "@alienplatform/core"

const data = new alien.Storage("data").build()
const cache = new alien.Kv("cache").build()

const api = new alien.Worker("api")
  .code({ type: "source", src: "./api", toolchain: { type: "typescript" } })
  .permissions("execution")
  .build()

export default new alien.Stack("acme")
  .add(data, "frozen")
  .add(cache, "frozen")
  .add(api, "live")
  .permissions({
    profiles: {
      execution: {
        data: ["storage/data-read", "storage/data-write"],
        cache: ["kv/data-read", "kv/data-write"],
      },
    },
  })
  .build()

The execution profile becomes one cloud identity, and api runs as it with read and write access to data and cache only.

Permission layersCopy Anchor Link

ProfilesCopy Anchor Link

A profile maps resource ids to permission sets. Workloads pick one with .permissions("<name>").

AWS limits apply to each role:

ScopesCopy Anchor Link

profiles: {
  execution: {
    "*": ["storage/data-read"],
    "logs": ["storage/data-write"],
  },
}

A set's definition can bind more broadly than its key. On Google Cloud, sandbox/execute and sandbox/management bind at project scope under either key.

Management accessCopy Anchor Link

.permissions({
  profiles: { execution: { credentials: ["vault/data-read"] } },
  management: { extend: { credentials: ["vault/data-write"] } },
})

The management identity can't read or write values in your Vaults unless you extend it with vault/data-read or vault/data-write. Grant each only when it must read or write secret values.

Commands add worker/dispatch-command on the target Worker.

alien deploy --automatic-setup gives the management identity broader, stack-wide grants, such as for commands and vault sync.

Limits that always holdCopy Anchor Link

Whatever you grant:

• The management identity writes to the internal secrets vault, where Alien stores the environment secrets it supplies. On AWS, Google Cloud and Azure it can write values but not read them back. On Kubernetes it keeps read access. It never gets access to the deployer-secrets vault that customers write; an extend or override grant that would reach it fails the build.
• On AWS, when the stack has a Sandbox with an internet gateway, an explicit Deny stops the management identity from reading the secrets vault, even under automatic setup's broader grants. It protects the sandbox egress signing key.
• On AWS, the management identity can't change its own role or the roles initial setup creates for sandboxes. The Deny also applies to an override profile.
• On AWS, every role the management identity creates or changes carries the permissions boundary from initial setup. The management identity can't edit the boundary or remove it.
• On Azure, initial setup creates every custom role the deployment assigns later, for management and for each profile. The management identity can't create or edit role definitions.
• On Azure, a condition on the management identity's role assignments admits only the declared roles: management roles onto itself, and application roles onto the deployment's workload identities. It can't assign any other role, such as Owner, or assign to any other identity.

Cloud actions per setCopy Anchor Link

Each set maps to specific cloud actions per platform. For example, storage/data-read includes s3:GetObject, s3:GetObjectVersion, and s3:ListBucket on AWS, and storage.objects.get, storage.objects.list, and storage.buckets.get on Google Cloud. The definitions are in alien-permissions/permission-sets.

Custom permission setsCopy Anchor Link

Pass an inline object where a set name would go:

import * as alien from "@alienplatform/core"

const assumeVendorRole: alien.PermissionSet = {
  id: "assume-vendor-role",
  description: "Assume a role in the vendor account with an external id",
  platforms: {
    aws: [{
      grant: { actions: ["sts:AssumeRole"] },
      binding: {
        stack: {
          resources: ["*"],
          condition: { StringEquals: { "sts:ExternalId": "acme-external-id" } },
        },
      },
    }],
  },
}

export default new alien.Stack("acme")
  .permissions({
    profiles: { execution: { "*": ["storage/data-read", assumeVendorRole] } },
  })
  .build()

A platform without entries gets no grant from that set.

Built-in setsCopy Anchor Link

Sets used in profiles:

Sets used by initial setup and the management identity, derived automatically:

NextCopy Anchor Link

• Permissions in the guide
• Stack
• ServiceAccount