zapscript

package
v2.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 3, 2026 License: GPL-3.0 Imports: 51 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	MIMEZaparooZapScript  = "application/vnd.zaparoo.zapscript"
	WellKnownPath         = "/.well-known/zaparoo"
	HeaderZaparooOS       = "Zaparoo-OS"
	HeaderZaparooArch     = "Zaparoo-Arch"
	HeaderZaparooPlatform = "Zaparoo-Platform"
)
View Source 
const ExecuteTimeout = 2 * time.Second

ExecuteTimeout is the maximum duration for execute commands.

View Source 
const MaxScriptLength = 8192

MaxScriptLength bounds ZapScript text accepted from any untrusted source, measured in bytes.

Parse cost grows with the length of the text, so an unbounded script is a way to occupy the single token worker and, once stored, to make every later history read expensive. The limit sits well above anything legitimate: an NTAG216, the largest tag in common use, holds 888 bytes.

View Source 
const RedactedPlaceholder = "[redacted]"

RedactedPlaceholder replaces a bearer credential in text that is logged, stored, or returned to API clients.

Variables

View Source 
var (
	ErrArgCount     = errors.New("invalid number of arguments")
	ErrRequiredArgs = errors.New("arguments are required")
	ErrRemoteSource = errors.New("cannot run from remote source")
	ErrFileNotFound = errors.New("file not found")
	ErrNoHistory    = errors.New("no play history available")
	// ErrInvalidScript wraps a ZapScript parse failure.
	ErrInvalidScript = errors.New("invalid ZapScript")
	// ErrUnknownCommand is returned for a command name with no handler.
	ErrUnknownCommand = errors.New("unknown command")
	// ErrCommandBlocked is returned for a command denied by configuration.
	ErrCommandBlocked = errors.New("command blocked")
	// ErrExecuteNotAllowed is returned when a command line is denied by the
	// allow_execute config.
	ErrExecuteNotAllowed = errors.New("execute not allowed")
)
View Source 
var (
	ErrNoActiveMedia         = errors.New("no active media")
	ErrNoLauncher            = errors.New("no launcher associated with active media")
	ErrNoControlCapabilities = errors.New("no control capabilities")
	ErrNoLauncherCache       = errors.New("launcher cache not available")
)
View Source 
var (
	ErrInputNotAllowed = errors.New("input key not allowed")
	ErrInputBlocked    = errors.New("input key blocked")
)
View Source 
var (
	// ErrExtendSourceNotReader is returned when an extension is attempted
	// from anywhere but a physical reader.
	ErrExtendSourceNotReader = errors.New("playtime extensions can only be granted by scanning a card")
	// ErrExtendNotAlone is returned when an extension shares a script with
	// other commands.
	ErrExtendNotAlone = errors.New("playtime.extend must be the only command on a token")
	// ErrExtendProfileMissing is returned when the authorizing profile
	// argument is absent.
	ErrExtendProfileMissing = errors.New("playtime.extend requires a profile argument")
)
View Source 
var AcceptedMimeTypes = []string{
	MIMEZaparooZapScript,
}
View Source 
var ErrControlCommandNotAllowed = errors.New("command not allowed in control context")
View Source 
var ErrHTTPNotAllowed = errors.New("HTTP URL not allowed")
View Source 
var ErrNoPlaylistActive = errors.New("no playlist active")

ErrNoPlaylistActive is returned by playlist control commands when no playlist is active for the requested slot. This is an expected user condition (firing a playlist command with nothing playing), so callers log it at Warn, not Error.

View Source 
var ErrScriptTooLong = errors.New("zapscript exceeds maximum length")

ErrScriptTooLong is returned for text over MaxScriptLength. Such text is rejected before it is parsed or stored.

View Source 
var ErrWellKnownNotFound = errors.New("well-known endpoint not found")

ErrWellKnownNotFound is returned when the .well-known/zaparoo endpoint returns 404, indicating the host does not support Zaparoo.

Functions

func ConfigureHTTPTransport added in v2.11.0 

func ConfigureHTTPTransport()

ConfigureHTTPTransport applies the process TLS root configuration to ZapLink's custom timeout transport.

func ForLog added in v2.17.1 

func ForLog(text string) string

ForLog returns text safe to write to a log line: bearer credentials replaced, and anything longer than MaxScriptLength truncated.

The truncation is what makes this usable from a reader driver, which logs whatever a tag holds before anything has bounded it. A legitimate script is never affected, because a longer one is rejected rather than run, so the only text this shortens is text that was never going to do anything except fill a log that lives in tmpfs.

func GetExprEnv added in v2.10.0 

func GetExprEnv(
	pl platforms.Platform,
	cfg *config.Instance,
	st *state.State,
	scanned *zapscript.ExprEnvScanned,
	launching *zapscript.ExprEnvLaunching,
) zapscript.ArgExprEnv

func GetLauncherIDs added in v2.17.0 

func GetLauncherIDs(pl platforms.Platform, cfg *config.Instance) []string

GetLauncherIDs extracts launcher IDs from the platform for validation context.

func HasSensitiveScript added in v2.17.0 

func HasSensitiveScript(text string) bool

HasSensitiveScript reports whether text involves a bearer credential, so callers can also drop adjacent raw copies such as a token's data payload.

This keys off the command rather than the value: a token whose text has already been redacted may still have an unredacted raw payload beside it. Text that names a credential-bearing command but cannot be parsed is treated as sensitive, since an unreadable script cannot be shown to be free of credentials.

func IsControlCommand added in v2.10.0 

func IsControlCommand(cmdName string) bool

IsControlCommand returns true if the command is the control command. The control command is blocked in control context to prevent recursion where a control's Script invokes another control command.

func IsMediaDisruptingCommand added in v2.11.0 

func IsMediaDisruptingCommand(cmdName string) bool

IsMediaDisruptingCommand returns true if the command would change or stop the currently playing media. Used by launch guard to decide whether a token should be staged for confirmation.

func IsMediaLaunchingCommand added in v2.7.0 

func IsMediaLaunchingCommand(cmdName string) bool

IsMediaLaunchingCommand returns true if the command launches media and should be subject to playtime limits.

func IsPlaylistCommand added in v2.10.0 

func IsPlaylistCommand(cmdName string) bool

IsPlaylistCommand returns true if the command is a playlist command. Playlist commands require a PlaylistController and are not safe in control context.

func IsValidCommand added in v2.9.0 

func IsValidCommand(cmdName string) bool

IsValidCommand returns true if the command name is a valid ZapScript command.

func ParseAdvArgs added in v2.8.0 

func ParseAdvArgs[T any](pl platforms.Platform, env *platforms.CmdEnv, dest *T) error

ParseAdvArgs parses and validates advanced arguments for a command. Returns an error if parsing or validation fails.

func PreWarmZapLinkHosts added in v2.8.0 

func PreWarmZapLinkHosts(db *database.Database, checkInternet func(int) bool)

PreWarmZapLinkHosts pre-warms the DNS and TLS cache for known zaplink hosts. This is called during startup to reduce latency on first zaplink access. It makes HEAD requests to /.well-known/zaparoo for each supported base URL.

func PreWarmZapLinkHostsContext added in v2.11.0 

func PreWarmZapLinkHostsContext(
	ctx context.Context,
	db *database.Database,
	checkInternet func(context.Context, int) bool,
)

func PressGamepadSequence added in v2.10.0 

func PressGamepadSequence(pl platforms.Platform, args []string, interKeyDelay time.Duration) error

PressGamepadSequence is shared between ZapScript commands and API handlers. interKeyDelay sets the gap between button presses; pass 0 to use the default.

func PressKeyboardSequence added in v2.10.0 

func PressKeyboardSequence(pl platforms.Platform, args []string, interKeyDelay time.Duration) error

PressKeyboardSequence is shared between ZapScript commands and API handlers. interKeyDelay sets the gap between consecutive key presses; pass 0 to use the default (100 ms). If the platform implements keyboardSequencer, the full args slice is handed off; otherwise falls back to pressing each key individually.

func RedactScript added in v2.17.0 

func RedactScript(text string) string

RedactScript removes bearer credentials from ZapScript text while leaving everything else readable, so logs and history stay useful for diagnosis. A profile card keeps its command name; an extension card additionally keeps its amount, which is the part worth auditing.

Credential values are replaced in the original text rather than the script being re-rendered from the parse tree, so traits, spacing and any command this function does not know about survive untouched.

It fails closed. Text that names a credential-bearing command but cannot be parsed, or whose credentials survive the replacement, is replaced wholesale.

func RedactToken added in v2.17.0 

func RedactToken(text, data string) (redactedText, redactedData string)

RedactToken returns a copy of a token safe to log, store, or return to API clients. The raw data payload is dropped entirely for sensitive tokens: it is an unparsed copy of the same content, so it cannot be redacted in place.

Both answers come from a single parse. This is the hottest redaction entry point: it runs twice per scanned token on the service worker and once per row on every history read.

func RunCommand 

func RunCommand(
	serviceCtx context.Context,
	pl platforms.Platform,
	cfg *config.Instance,
	plsc playlists.PlaylistController,
	token tokens.Token,
	cmd zapscript.Command,
	totalCmds int,
	currentIndex int,
	db *database.Database,
	opts RunCommandOptions,
	exprEnv *zapscript.ArgExprEnv,
) (platforms.CmdResult, error)

RunCommand parses and runs a single ZapScript command.

func RunControlScript added in v2.10.0 

func RunControlScript(
	ctx context.Context,
	pl platforms.Platform,
	cfg *config.Instance,
	db *database.Database,
	script string,
	exprEnv *gozapscript.ArgExprEnv,
) error

RunControlScript parses and executes a zapscript string in control context. All commands are validated before any are executed to prevent partial execution. The exprEnv is passed directly to each command instead of building from state.

func ValidateScriptLength added in v2.17.1 

func ValidateScriptLength(text string) error

ValidateScriptLength rejects ZapScript text longer than MaxScriptLength. Callers must apply it at the point untrusted text enters the system, before the text reaches a parser.

Types

type ArgPlaylist 

type ArgPlaylist struct {
	ID    string            `json:"id"`
	Name  string            `json:"name"`
	Items []ArgPlaylistItem `json:"items"`
}

type ArgPlaylistItem 

type ArgPlaylistItem struct {
	Name      string `json:"name"`
	ZapScript string `json:"zapscript"`
}

type RunCommandOptions added in v2.16.0 

type RunCommandOptions struct {
	WaitForMediaReady  func(context.Context) error
	AcquireMediaLaunch func() (platforms.MediaLaunchAccess, error)
	BeforeExit         func()
	PlaybackManager    audio.PlaybackManager
	UI                 *uievents.Service
	LauncherManager    *state.LauncherManager
}

RunCommandOptions groups optional services used by specific command types.

type WellKnown 

type WellKnown struct {
	Trusted   []string `json:"trusted,omitempty"`
	ZapScript int      `json:"zapscript"`
	Auth      int      `json:"auth,omitempty"`
}

func FetchWellKnown added in v2.10.0 

func FetchWellKnown(baseURL string) (*WellKnown, error)

FetchWellKnown fetches and parses the .well-known/zaparoo file from a base URL. Returns ErrWellKnownNotFound if the host returned 404.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.