Building an app

Building an app

Find or publish a type, sign in, write into the user’s repo and read back through the platform.

A Techne app is an ordinary atproto app: records live in each user’s repo on their PDS; the platform indexes them, applies permissions and serves reads. SDK: npm i techne-sdk (also a Rust crate); docs: techne.computer/docs/quickstart.html. In order: find or publish the type (publishing is a signed-in call, see Types), host the client metadata, sign in naming the types you write, put, read back.

Sign-in

Standard atproto OAuth, no registration. The app is its client metadata URL (client_id): name, logo and homepage come from that document; its scope is atproto, one repo:<nsid> per type it writes, and for private data the permissioned methods (include:pub.techne.draft.authPermissioned) plus a space: scope (see Private and shared data). The SDK builds this least-privilege list for you (scopes(), the default of signIn and clientMetadata; see Permissions). In the SDK, connect(session, TECHNE_PLATFORM_DID) (did:web:techne.computer, from techne-sdk/auth) gives the clients over the signed-in session.

On techne.town (our PDS) the consent page says “Built by Techne” only for our own listed apps; any other app gets a community-app warning scaled to its scope.

Mobile apps use Universal Links (iOS) or App Links (Android) for the OAuth redirect. In development, atproto’s loopback client (client_id http://localhost?..., redirect to http://127.0.0.1) needs no hosted metadata. Its client_id carries its scope and redirect, so its private app space changes when the port or the types change. It is for development only: a loopback client_id is not an app identity (any app can present the same one). The browser keeps one stored session per origin: sign out before switching client ids on one origin. Ship with hosted client metadata.

Permissions

What an app asks for decides what it can do and which consent page the person sees. Ask for the least that works.

  • atproto: required; signs the person in. Reaches nothing by itself.
  • repo:<nsid> (one per type the app writes): create, edit and delete those public records in the person’s repo.
  • include:pub.techne.draft.authPermissioned: the permissioned.* calls (private writes, reads, deletes, changes, grants). It reaches only the spaces the space: scopes name.
  • space:pub.techne.draft.space.private?skey=<appKey>: the app’s own private space, which no other app sees (appKey = base32 of the SHA-256 of the client_id; SDK appKey, appSpace). Any other space: scope reaches other private data.
  • rpc:<method>?aud=did:web:techne.computer%23atproto_appview: one platform call. The SDK asks for query.listRecords, countRecords, getRecords, registry.getType, listTypes, sync.indexRecord (with types) and registry.publishType (with publish: true). The platform narrows the queries to public data and the app’s own space.
  • include:pub.techne.draft.authRead: read everything the person may see through the platform, private spaces they belong to included (SDK everything: 'read').
  • include:pub.techne.draft.authWrite: write every public pub.techne record and private ones in any space they can write (SDK everything: 'write', with authRead).
  • include:pub.techne.draft.authCommons and authOperator: the Commons API’s views, and its operator actions (refused for anyone who is not an operator).

On techne.town the consent page shows one of three community banners: public records only; public records plus the app’s own space; or a red warning when the app can read or write other private data (authRead, authWrite, any other space: scope, or a call we can’t bound). The SDK’s defaults, with types and publish, stay off the red one.