Authentication

What an app sends

Your app gets the user context when the person signs in to it with ChirpAuth and asks for the scope openid drive.grant: it is the access_token in the token response. ChirpAuth issues drive.grant only to clients Stackwell has enabled; developers can’t enable it for themselves.

What Drive checks

On every request, before it touches any file:

1. The machine token is a valid ChirpAuth machine token.
2. The user context is a valid ChirpAuth access token, not expired, with audience drive and scope drive.grant.
3. Drive asks Granite whether the grant is approved and still active. If the person has revoked it, or it has expired, the request is refused (403). If Drive can’t get an answer from Granite, the request fails (5xx); it never goes ahead unchecked.
4. The grant belongs to the person in the user context, and its subject is your machine token’s sub.
5. The grant covers the action: drive.read to read, drive.write to write. A grant with only drive.read can’t write. A grant with only drive.write can’t read, and its writes answer without what it can’t read: a file comes back without content or content_hash, a table row with empty cells.
6. The grant covers the file: see What a grant covers.

A user context on its own grants nothing, and neither does a machine token: without a grant, an app reaches no one’s files (403).

What a grant covers

Name Drive resources in the Granite request’s requested_resource (and requested_resources, for more than one):

Ask for the narrowest one that works; a folder of your own is usually right. The folder id can be any UUID your app picks. If the person has no folder with that id, Drive creates it on your app’s first write into it.

Within a grant over folders:

• New files must name one of the granted folders in directory_id. A file placed anywhere else, or nowhere, is refused (403).
• Listings show only files in the granted folders.
• A file outside them can’t be read or changed, even if your app knows its id.
• Moving a file out of them is refused.

Several apps can hold grants over the same folder; each sees the files the others put there.

Resources in one grant don’t widen each other. A grant over a folder plus storage:drive:drive:files reads every file but still changes only files in the folder.

A grant over files does not cover Drive’s folder routes (/v1/directories) or the usage report (/v1/usage); with a file grant they answer 403.

What a grant never allows

Permanently deleting a file is the person’s alone, whatever the grant says: DELETE /v1/files/{id} returns 403 to an app. Apps can move files to the trash instead.

People

People sign in to the Drive app at https://drive.stackwell.tech with ChirpAuth. Drive accepts a person’s ChirpAuth sign-in only when it was issued to the Drive app; a person’s sign-in to your app is not accepted by Drive.