[vish727]

The two clients a nook's own code uses. They are to server code what nook.js is to a page: the same calls, the same rules, so a me/ collection means the same thing on both sides.

import nook_data

me = nook_data.viewer(self.headers)      # for whoever is making this request
me.create("me/notes", {"text": "only mine"})
me.user["email"]

nook_data.list("notes")                  # as the nook itself, from cron

const nook = require('./nook-data.js')
const me = nook.viewer(req.headers)
await me.create('me/notes', { text: 'only mine' })

viewer(headers) is the whole of the design

It takes the act-as token out of the request rather than an email address, so a nook acts for someone who is using it and can never act for someone it merely names. Passing headers straight through is also the easier thing to write than looking up an address, which is the point — the safe path should be the obvious one.

The skill file says this in as many words, because an agent that reaches for an email address is the failure mode.

Details worth a look

• Standard library only on both sides: urllib and Node 22's built-in fetch. A nook has no build step, so a helper that needed installing would not be a helper.
• nook-data.js is CommonJS, which is what Node uses for a .js file in a folder with no package.json — the normal case for a nook. The file says in one line what to do if the author sets "type": "module".
• Headers are read whichever shape they arrive in: a plain object from node:http, a Headers, a dict, or a WSGI environ. Tested for the case-insensitive path.
• Both raise a typed error carrying the HTTP status, and say plainly when they are not running inside a nook rather than failing on an empty URL.
• helpers/embed.go exposes them for nook-init to write beside the nook's files, so they always match the server they talk to. Both names are reserved.

Skill file

A new section on when a nook needs a server at all — an API key that must not reach a browser, a service that will not allow one, or work on a schedule — then the four manifest fields, nook secret set, and what the code is given and is not: identity, never a credential. It also states the fence and that nothing survives a restart, since that is the thing an author will otherwise assume wrongly. nook logs and nook secret join the command list.

Ready to tag as v0.6.0. nookd then writes these at boot in the fly PR.

Part of ENG-24