Policy actions

[!caution]

This service is not deployed. There is no iam.shelfcs.com or sts.shelfcs.com in the published endpoint list, and no call on this page will answer. This page is the specification, not a description of something running.

For the identity system that does exist — the identity service users, one project, one role, and EC2 access keys — read Identity, as deployed.

Objective

Policies decide what an identity may do. These actions create them, version them, attach them and read them back.

Permissions

Action	Resource scope
`iam:CreatePolicy`, `iam:DeletePolicy`	`policy/<name>`
`iam:GetPolicy`, `iam:GetPolicyVersion`, `iam:ListPolicies`	`policy/*`
`iam:CreatePolicyVersion`, `iam:SetDefaultPolicyVersion`	`policy/<name>`
`iam:AttachUserPolicy`, `iam:DetachUserPolicy`	Both `user/<name>` and `policy/<name>`
`iam:PutUserPolicy`, `iam:DeleteUserPolicy`	`user/<name>`

The attach and detach actions evaluate against both the identity and the policy.

[!warning]

An identity holding iam:AttachUserPolicy and iam:CreatePolicy can grant itself any permission in the account. There is no permission boundary in v1 to constrain that. Treat those two actions as equivalent to full administrative access, and grant them accordingly.

Instructions

Managed and inline

Managed policies are standalone documents with their own ARN, attachable to many identities, and versioned. Use them for anything reused.

Inline policies are embedded in one identity, have no ARN of their own, are not versioned, and are deleted with the identity. Use them for permissions that belong to exactly one identity and should not outlive it.

CreatePolicy

Parameter	Type	Required	Notes
`PolicyName`	string	Yes	Immutable after creation
`PolicyDocument`	string	Yes	URL-encoded JSON
`Path`	string	No
`Description`	string	No	Immutable after creation

PROPOSED: a policy document is at most 6144 characters, counted with whitespace removed.

The document is validated at creation. A document that does not parse, names a malformed ARN, or uses a construct we do not implement is rejected with MalformedPolicyDocument — never accepted and then evaluated differently from what it says.

That rule matters most for any construct in the policy language we do not support: silently ignoring an unsupported Condition would turn a restrictive policy into a permissive one, which is the worst possible failure mode for this service.

Response: the Policy — PolicyName, PolicyId, Arn, DefaultVersionId, AttachmentCount, CreateDate, UpdateDate.

Versions

A managed policy is not edited in place. CreatePolicyVersion adds a version, optionally making it the default:

Parameter	Type	Required	Notes
`PolicyArn`	string	Yes
`PolicyDocument`	string	Yes
`SetAsDefault`	boolean	No	Default `false`

PROPOSED: five versions per policy, matching what tooling expects. The sixth returns LimitExceeded; delete an old version first.

Only the default version is evaluated. A new version created without SetAsDefault changes nothing until SetDefaultPolicyVersion is called — which is what makes a policy change reviewable before it takes effect, and instantly reversible afterwards by setting the previous version back.

Attachment

Action	Attaches to
`AttachUserPolicy` / `DetachUserPolicy`	A user
`AttachGroupPolicy` / `DetachGroupPolicy`	A group
`AttachRolePolicy` / `DetachRolePolicy`	A role
`ListAttachedUserPolicies`	Lists what is attached to a user

Attaching an already-attached policy succeeds and changes nothing.

A policy cannot be deleted while attached to anything: DeletePolicy returns DeleteConflict until every attachment is removed.

Inline policies

Action	Purpose
`PutUserPolicy`	Write an inline policy; overwrites by name
`GetUserPolicy`	Read one
`ListUserPolicies`	Names of inline policies on a user
`DeleteUserPolicy`	Remove one

PutUserPolicy overwrites without warning. There is no version history and no undo — the previous document is gone. This is the practical reason to prefer managed policies for anything that matters.

Reading a policy back

GetPolicy returns metadata only, not the document. GetPolicyVersion returns the document, URL-encoded.

To answer “what can this user do”, a caller must gather: inline policies on the user, managed policies attached to the user, and both again for every group the user belongs to. There is no single call that returns an effective permission set, and no policy simulator in v1.

OPEN (Michael): whether a policy simulator exists in v1. Without one, the only way to test a policy is to hold the credential and try the call — which is what DryRun on the EC2 actions is for.